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Preface 


I  became  intrigued  with  real-time  systenis  in  the  spring  of  Here  was  an 

application  domain  where  using  formal  methods  is  justified,  because  the  cost 
in  life  and  property  of  programmer  errors  could  be  so  great.  Here  also  was  an 
application  domain  where  making  assumptions  about  hardware  failure  modes 
is  inappropriate,  and  so  a  system  must  lie  able  to  tolerate  so-called  Hyzanline 
failures.  My  research  efforts  had  been  concerned  with  the.se  two  subjects,  thus 
putting  me  in  the  enviable  position  of  having  discovered  a  problem"  for  my 
various  ‘'solutions”. 

Attacking  a  real  process-control  problem  seemed  like  a  good  way  to  get  a 
better  understanding  of  the  area.  But,  which  problem?  'I'he  {iroblem  bad  to 
be  simple  enough  so  that  Computer  Science  issues  dominated  any  application- 
dependent  details.  Yet.  the  problem  could  not  be  too  simple  or  else  some  key 
aspect  of  real-time  systems  might  be  overlooked.  1  was  aware  that  various 
research  groups  (e  g.,  at  University  of  Newcastle  upon  Tyne  and  at  Universitv 
of  Waterloo)  had  u^^ed  electric  toy  trains  as  a  vehicle  [sic]  for  such  research, 
and  so  that  was  an  obvious  place  to  start.  After  studying  a  bit  of  railroading, 
however,  it  became  clear  that  toy  trains  are  not  accurate  models  of  reality 
they  change  the  problem  too  much.  For  example,  real  trains  cannot  accelerate 
or  decelerate  as  rapidly  as  toy  trains  do.  Therefore,  a  control  program  for 
a  real  train  must  anticipate  changes  to  train  speed:  a  control  program  for  a 
toy  train  need  not.  Some  of  the  inaccuracies  of  toy  trains  ran  be  corrected 
by  modifying  the  electronics  used  to  control  the  trains,  but  dealing  with  this 
and  the  other  custom  hardware  necessary  for  integrating  a  toy  train  set  with 
a  computer  system  seemed  like  a  black  hole  (as  only  custom  hardware  can  be) 
that  I  should  avoid.  Thus,  I  decided  to  build  a  railroad  simulator  along  with 
support  software  for  constructing  railroad  layouts,  controlling  those  layouts  from 
networks  of  computers,  and  monitoring  such  control  experiments. 

After  the  first  version  of  the  railroad  simulator  was  built,  it  became  clear 
that  my  circumstances  were  not  unique.  Other  scientists  were  also  becoming 
interested  in  studying  real-time  programming  issues  and  they.  too.  felt  that  a 
prototype  application  could  be  a  useful  research  tool.  Courses  on  real-time  sys¬ 
tems  would  benefit  from  using  this  software  in  laboratory  exercises,  particularly 
because  specialized  hardware  and  software  were  not  required.  So,  we  cleaned- 
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up  the  code,  wrote  some  user  docuinetitHlioii.  and  pul  tof^ether  this  software 
distribution. 

'I'iie  Trainset  system,  as  our  railroad  .simulation  .software  is  now  known, 
is  the  work  of  man>  people  over  the  last  .5  years,  Jacob  .^ixikovvitz  defined 
our  model  of  railroads  and  wrote  the  first  railroad  simulator  in  the  spring  of 
1987:  it  ran  under  Sl’NOS  Lni.x.  Jacob  afso  supervised  MEng.  students  Ellen 
Blood.  Anthony  Fellegrini.  and  Jane  Smidesang  in  producing  an  XIO  graph¬ 
ics  interface  to  the  system.  Michael  Abbott,  an  undergraduate,  then  defined 
and  implemented  a  highdevel  interface  to  the  simulator  for  use  by  control  pro¬ 
grams.  'This  software  was  then  rewritten  and  ported  to  \'.M.S.  EEfRlX.  and 
X 1 1 /DEC'VVindows  by  7ony  Lekas.  a  DEC  engineer  working  with  us  as  part  of 
a  DEC-funded  research  project  at  Cornell.  Dick  Brown  joined  the  project  in 
Eall  HI89.  spending  that  year  and  the  following  spring  term  on  a  major  rewrite 
of  the  system  and  writing  documentation  for  what  we  had  Dick  was  assisted 
by  Thomas  Rres.soud.  who  rewrote  and  documented  the  layout  editor  atid  part 
of  the  graphu's  monitor  software.  Most  recently.  Donald  Wiliardja  has  helped 
us  debug  the  installation  procedure. 

This  software  develofmient  effort  would  not  have  been  possible  without  fi 
nancial  support  from  a  number  of  sources.  My  research  in  concurrent  and 
distributed  system.s  has  been  funded  by  grants  from  the  National  Science  Foun¬ 
dation  since  1978  and  from  the  Office  of  Naval  Research  since  198a.  Dr.  .4ndre 
van  'I'llborg.  now  the  division  director  for  C’omputer  Science  at  ONR.  was  es¬ 
pecially  supportive  as  my  ONR  program  manager  during  the  initial  stages  of 
this  project,  and  Gary  Koob,  his  succe.s.sor.  has  continued  that  tradition.  Fund¬ 
ing  from  Digital  Equipment  Corporation  was  also  critical  to  the  success  of  this 
project,  Ed  Balkovich  of  DEC  encouraged  me  to  apply  for  funding  under  Digi¬ 
tal’s  External  Research  Program  (ERP)  and  then  served  as  our  corporate  liaison, 
helping  to  transfer  our  research  results  to  engineers  at  DEC  who  could  benefit 
from  them.  The  DEC  ERP  funds  allowed  us  to  procure  hardware  for  the  labo¬ 
ratory  used  to  develop  this  softw'are  and  to  run  real-time  systems  experiments. 
John  Gannon,  the  Software  Engineering  Program  manager  at  NSE  for  1988-89, 
alerted  me  to  the  NSF  Softw'are  Capitalization  Initiative  and  encouraged  me  to 
apply.  Funding  from  that  program  supported  Dick  Brown's  slay  at  Cornell  and 
is  largely  responsible  for  transforming  our  research  prototype  into  a  system  that 
could  be  w'idely  distributed. 


Fred  B,  Schneider 
Ithaca,  New  York 


Chapter  0 

Introduction  and  Overview 


Trainset  is  a  real-time  simulation  of  a  railroad.  The  software  cotisists  of  a  sim¬ 
ulator.  an  interactive  graphics  editor  for  defining  railroad  layouts  and  graphics 
monitor  programs  for  displaying  the  slate  of  the  railroad  and  manually  control¬ 
ling  it.  Two  communications  interfaces  to  the  simulator  are  provided, 

•  The  control  program  interface  (CPI)  is  used  by  computer  programs  that 
control  Trainset  railroads.  The  CPI  consists  of  library  routines  and  data 
stTUClures,  collectively  called  the  ACl  (Automatic  (,'ontrol  Interface),  and 
low-level  message  formats  and  related  facilities,  called  the  Lhl  (Low-Level 
Interface). 

•  The  monitor  interface  is  used  only  by  the  graphics  monitor  programs. 

These  interfaces  can  be  in  use  simultaneously. 

Trainset  has  been  implemented  in  C  language  on  Digital  Kquipment  Corp. 
l.'llrix,  using  DECwindows/X-1 1  andT(,'P/IP  or  DECnet. 

This  manual  introduces  Trainset  and  gives  specifications  for  the  railroads  it 
implements.  The  document  also  discu.s.se.s  the  mechanics  of  using  Trainset  and 
provides  other  information  that  a  re.searcher  or  student  should  know  in  order  to 
write  control  programs  that  interact  with  Trainset  railroad  layouts. 

d'he  manual  is  organized  a.s  follows. 

Chapter  1  is  a  tutorial  on  using  the  software.  It  includes  instructions  for 
running  a  demonstration,  creating  and  simulating  a  railroad  layout  and  writing 
programs  to  control  a  Trainset  railroad.  A  simple  programming  example  is 
discussed  to  illustrate  the  use  of  the  ACL 

Chapter  2  .specifies  the  attributes  of  .simulated  railroads  that  Trainset  sup¬ 
ports. 

Chapter  .'1  discusses  the  ACL  A  high-level  mechanism  is  presented  for  estab¬ 
lishing  a  connection  with  a  running  Trainset  railroad  simulation  and  receiving 
an  initial-state  download  of  that  railroad.  Commands  and  queries  are  described 
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for  interacting  with  a  Trainset  railroad.  I'tility  routines  lliat  provide  timer 
facilities  are  introduced,  and  a  service  is  discu.ssed  liiat  supfiorts  the  writing  of 
fault-tolerant  control  programs. 

Chapter  4  documents  the  LIJ,  This  informal ioti  will  be  of  interest  to  pro¬ 
grammers  who  wish  to  bypass  the  ACI  layer  or  reimplement  it  for  other  envi¬ 
ronments. 

I'he  appendices  include  reference  pages  for  tiie  programs  that  conijirise 
Trainset  and  selected  code  listings, 

A  separate  installation  guide  accompanies  the  software  distribution. 


Obtaining  a  Copy 

You  may  obtain  a  copy  of  the  Trainset  software,  installation  instructions  and 
the  text  of  this  manual  from  either  of  the  Internet  sites  listed  below. 

•  ftp.cs.cornell.edu  (Cornell  University) 

•  ftp.  stolaf  .  edu  (St.  Olaf  College) 

In  either  case,  u.se  the  file-transfer  program  ftp  to  open  a  connection  to  the 
desired  host.  Use  tlie  login  name  anonymous,  and  provide  your  own  Internet 
address  a.s  the  password. 

\fter  logging  in,  issue  the  ftp  command  cd  pub/trainset  to  access  the 
Trainset  distribution  directory.  Among  the  files  in  that  directory  are: 

•  README,  which  briefly  describes  Trainset  and  the  contents  of  the  distri¬ 
bution  directory. 

•  install. dvi.  installation  manual  for  Trainset  (in  Tj-'X  output  format). 

•  ts.dvi.  the  text  of  this  manual,'  and 

•  trainset .  tar .  Z.  the  source  code  package  for  Trainset. 

See  the  manual  page  for  ftp{  1 )  for  file  transfer  instructions.  Use  ftp  file  type 
binary  for  .dvi  and  .tar.Z  files.  The  .source  code  package  trainset . tar .  Z 
may  be  unpacked  on  most  Unix  systems  by  issuing  the  following  command; 

V,  zcat  trainset. tar.Z  I  tax  xvf  - 
See  the  manual  pages  for  compfe‘5.s(  1 )  and  tar(l)  for  more  information  about 
this  unpacking  procedure. 


*To  print  this  manual  complete  with  figures,  install  Tiainsst  al  your  local  site  and  follow 
the  printing  instructions  provided  in  the  installation  manual. 
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Chapter  1 

Trainset  User’s  Guide 


1.1  Getting  Started 

Trainset  consists  of  programs  to  support  interaction  with  a  siinulat^'d  railroad, 
l.’sers  can  control  the  railroad  manually  and  watch  it  in  action  by  using  graph7c.s 
monitor  programs.  In  addition  computer  programs,  called  ronirol  programs. 
may  be  written  to  control  a  Trainset  railroad. 

The  rest  of  this  section  gives  you  a  chance  to  get  acquainted  with  Trainset. 
In  subsequent  sections  we  explain  how  to  create  and  run  your  own  railroad 
layout  and  how  to  use  the  ACl  library. 

1.1.1  Invoking  the  Programs 

To  start  the  Trainset  software,  enter  the  following  commaiid. 

*/.  ts 

(The  symbol '/,  is  assumed  to  be  your  shell  prompt.)  Three  windows  will  open 
on  your  display,  as  shown  in  Figure  I.l.  One  of  these,  the  Simulator  Window, 
is  a  terminal  window  that  displays  messages  from  the  simulation.  The  other  two 
windows  make  up  the  graphics  monitor.  The  Viewer  window  shows  the  current 
positions  of  the  railroad  tracks  and  trains  in  a  simulation.  The  Control  Panel 
window  has  controls  and  indicators,  including  pushbuttons  and  .slide  bars;  it  is 
a  graphical  interface  for  controlling  trains  and  switch  blocks  manually.' 

The  sample  railroad  layout  displayed  in  the  Viewer  window  of  Figure  I.l 
has  two  trains  and  24  blocks.^  Each  train  has  two  ends;  one  is  railed  the  head 

•  The  names  of  the  programs  that  comprise  Trainset  are  tsim  for  the  simulator,  tavieii  for 
the  Vieser,  tspanal  for  the  Control  Panal  emd  tssd  for  the  layout  editor,  tsad  is  discussed 
in  Section  1.2  below. 

■*A  careful  reader  may  observe  that  the  24  block  identifiers  in  Figure  1.1  range  from  I  to 
•5  and  7  to  2.7.  Identifier  f>  is  associated  with  a  subblock  of  the  cross  block  cr  6.  as  explained 
in  .Section  2.2.3. 
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Figure  1.1;  Sample  railroad  layout 
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(indirated  by  an  aiiftle  brai'kt'l )  and  tin-  i>llier  i>  calied  tlif-  Inti  (iiidn'ated  b\  a 
i^qiiare  bracket  )  A  Idock  s  type  (see  Section  'J  "J)  is  detined  t^y  its  label 

rg  for  rtgular  blocks. 

St  for  slalion  bii'cks. 

jn  for  jotn  blo<  ks. 

cr  for  cross  blocks  and 

s»  for  strtlrh  blocks. 

Most  blocks  in  the  layout  of  Figure  l  .i  are  represented  by  straiglit  hues  or  arcs, 
e.g..  those  labelled  rg  1.  rg  2  and  st  11.  Five  such  blocks  are  thickened  to 
indicate  that  they  are  occupied  by  a  tram  'l  iiree  blocks  (cr  S.  jn  8  and  ss  14) 
have  other  block  ty  pes  that  are  represented  by  circled  symbols  in  the  laycuit 

The  control  panel  comprises  one  stibwindovv  for  each  tram  and  a  pushiuition 
for  each  switch  block.  Fach  switch  block's  pushbutton  can  toggle  that  switch 
block's  setting  between  the  straight  and  turned  settings.  Fach  train’s  subwindow 
includes  the  following  controls  and  indicators. 

•  Two  slide  bars  labelled  Speed  and  Goal  that  display  the  tram's  current 
speed  atid  the  goal  speed  desired  for  tliat  trait). 

•  A  slide  bar  labelled  Throttle  for  setting  a  new  goal  speed  An  oiierat  tonal 
train  accelerates  or  decelerates  when  its  goal  speed  differs  from  its  current 
speed. 

•  'I'vvo  labels  showing  the  name  of  the  train  (e.g  ,  Tram  1)  and  its  state 
(Operational.  Derailed  or  Collided) 

•  d'wo  indicator  lights.  EinerStop  and  StaStop  The  EmerStop  light  is  illu¬ 
minated  whiie  the  train  is  performing  an  emergeiicy  stop  The  StaStop 
light  is  illuminated  when  the  train  is  capable  of  performing  a  station  s!o|i, 
described  later 

•  Three  pushbuttons.  EmerStop.  StaStop  and  Reverse  The  EmerStop 
pu.shbi.tton  can  be  used  to  begin  an  emergency  slop  of  the  train  The 
StaStop  pushbutton  can  be  used  to  enable  the  station-slop  feature  for 
that  train,  d'he  Reverse  pushbutton  changes  the  direction  of  the  train's 
motion  if  the  train  is  stopped. 

1.1.2  Using  the  Control  Panel 

The  best  way  to  familiari'/e  yourself  with  the  features  of  the  Control  Panel  is  to 
try  them,  observing  their  effects  as  displayed  in  the  Viewer  window  Below  are 
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some  suggested  steps  for  getting  acquainted  wiili  the  system  using  the  samjile 
layout  of  figure  1. 1.'* 

When  describing  graphics  manipiiiations.  we  will  use  liie  following  terms  for 
mouse-oriented  input  operations.  The  inou.se  button  to  press  and  release  is  the 
left  mouse  button  (for  standard  workstation  window  managers) 

•  'I'o  click  on  a  pushbutton  or  icon,  move  the  mouse  pointer  into  the  [lush' 
button  or  iron  area,  then  press  the  mouse  button  down  and  release  it 
immediately. 

•  To  drag  jroni  one  point  to  anothtr  in  a  window,  position  the  mouse  cursor 
at  the  starting  point,  then  press  the  mouse  button  and  hold  it  dowu 
while  moving  the  mouse  icon  to  the  finish  point  Finally,  release  the 
mouse  button 

•  To  drag  a  i^lidf  bar  to  a  value  v.  first  position  the  mouse  pointer  over  the 
inner  region  that  contains  the  indicator  arrow  for  that  slide  bar  graphic , 
Then,  press  the  mouse  button  and  hold  it  down  while  moving  the  mouse 
cursor  right  or  left  until  the  desired  value  v  is  displayed  on  the  numerical 
display.  Finally,  release  the  mouse  button.  Due  to  variation  in  graphics 
display  resolution,  it  may  not  be  possible  to  enter  arbitrary  desired  valiie.s 
using  a  slide  bar. 

Before  starting,  identify  the  controls  and  indicators  for  each  train  and  switch 
block  in  the  Control  Panel  window.  The  Speed.  Goal  and  Throttle  slide  bars 
for  each  train  display  the  initial  value  zero.  Each  train  is  oi>erational,  and 
neither  of  the  StaStop  and  EaerStop  indicator  lights  is  illuminated. 

[Click  (once)  on  the  pushbutton  for  the  switch  block  ss  14 

When  you  click  on  the  pushbutton,  the  switch  block  toggles  between  the  straight 
and  turned  settings.  Observe  that  there  is  a  delay  after  pres.smg  the  pushbutton 
before  the  switch  block  setting  actually  changes  on  the  screen.  This  delay  has 
two  causes:  communication  time  and  the  time  that  it  actually  takes  for  a  switch 
block,  which  is  a  large  mechanical  device,  to  change  setting. 

I  Click  on  the  switch  block  pushbutton  again  to  toggle  the  switch 
[block  back  to  the  straight  setting. 

Click  on  the  StaStop  and  EmerStop  pushbuttons  for  Train  2. 

Do  not  click  on  the  Reverse  pushbutton  for  Train  2  nor  any 
pushbuttons  for  Train  1  at  this  time. 

'  Suggested  actions  arc  enclosed  in  boxes. 


6 


Wiien  the  StaStop  indicator  light  is  on,  we  .say  that  train  is  in  station- 
stop  mode:  likewi.se.  the  EmerStop  indicator  light  shows  whether  the  train  is 
in  (tnergtncy-stop  mode.  Note  that  the  StaStop  indicator  light  can  he  ithiini- 
nated,  but  the  EmerStop  indicator  light  cannot  be  lUurninaled  yet.  An  opera¬ 
tional  train’s  station-stop  mode  can  be  enabled  or  disabled  wiiether  that  train 
is  moving  or  not.  Emergency-stop  mode  cannot  be  enabled  for  a  train  unless 
that  train  is  moving. 

We  are  now  ready  to  set  a  train  in  motion. 

Accelerate  Train  1  by  dragging  the  Throttle  slide  bar  for  that 
train  to  a  value  near  40  (m/sec). 

Notice  that  several  things  happen  when  you  do  this. 

•  The  goal  speed  indicator,  labelled  Goal,  now  shows  the  throttle  value. 

•  'Fhe  current  speed  indicator,  labelled  Speed,  begins  changing  from  the 
previous  speed  tzero  in  this  case)  towards  the  goal  speed. 

•  The  train  at  the  top  of  the  Viewer  window  begins  moving  (forward  towards 
the  left,  in  this  case). 

The  goal  speed  is  not  reached  instantaneously,  A  train  ordinarily  changes  speed 
at  a  fixed  rate  of  acceleration,  as  explained  in  Section  2.3.2.  and  it  takes  time 
to  accelerate  from  0  to  40  m/sec. 

Observe  that  a  block  is  highlighted  in  the  Viewer  window  if  any  part  of  that 
block  is  occupied  by  a  train. 


Drag  the  Throttle  slide  bar  to  about  .'io  m/sec.  then  drag  it  to 
about  4o  in/sec  before  the  train  has  completed  accelerating  to 
55  m/sec. 


This  exercise  shows  that  a  new  goal  speed  value  overrides  a  previous  one  when 
the  throttle  is  changed,  even  if  a  previous  goal  speed  has  not  yet  been  reached. 

There  is  a  maximum  speed  limit  of  60  m/sec  for  each  block  in  the  sample 
layout  of  Figure  1.1.  If  atrain  exceeds  this  limit,  that  train  derails.  All  minimum 
speed  limits  in  the  sample  layout  are  zero.  U.sing  the  editor  tsed  (see  Section  1 .2 
below)  it  is  possible  to  create  new  layouts  having  different  shapes  and  block 
speed  limits  or  to  modify  the  features  of  an  existing  layout.  However,  there  is 
no  provision  for  changing  the  attributes  of  a  layout  wdiile  it  is  being  simulated. 

Next,  request  an  emergency  stop. 

Click  on  the  EmerStop  pushbutton  for  Train  1.  1 


Observe  that  the  EmerStop  indicator  liglit  is  illuniinaled  winle  an  emergency 
stop  is  in  progress  and  goes  off  as  soon  as  the  stop  lias  completed  Another  way 
to  stop  a  train  is  by  simply  setting  that  train's  throttle  to  zero  An  emergency 
stop,  like  a  throttle  change,  overrides  any  prior  motion  plan.  Thus,  during  an 
emergency  stop  a  train's  Goal  speed  is  zero  and  its  current  speed  decreases 
toward  zero.  There  are  two  important  differences  between  using  the  throttle  to 
decelerate  to  zero  and  using  emergency  stop. 

•  Elmergency  stops  use  a  larger  deceleration  rate. 

•  Nothing  can  override  an  emergency  stop,  other  than  derailment  or  collision 
of  the  train. 

In  particular,  dragging  the  Throttle  slide  bar  has  no  effect  during  an  emergency 
stop.  Nor  does  an  emergency  stop  cause  the  throttle  bar  to  move.  The  throttle 
is  simply  ignored  until  the  emergency  .stop  has  completed  and  the  throttle  is 
dragged  again. 

vStation  blocks  differ  from  regular  blocks  in  that  they  have  a  statiori-.siop 
feature.  To  test  this  feature,  perform  the  following  steps. 

Click  on  the  StaStop  pushbutton  of  Train  1  so  that  the  StaStop 
indicator  light  becomes  illuminated  (station-stop  mode). 


Drag  that  train's  Throttle  slide  bar  to  30  m/,sec  or  less. 

The  next  time  that  Train  1  enters  a  station  block  (either  st  11  or  st  16).  it 
w'ill  immediately  begin  slowing  down  so  that  it  comes  to  a  halt  exactly  at  the 
oppo.site  terminator  of  that  block.  Three  conditions  are  required  for  a  train  to 
begin  performing  a  station  stop. 

•  That  train  must  have  station-stop  mode  enabled, 

•  That  train  must  have  speed  at  most  the  station-stop  speed. 

•  That  train  must  be  entering  a  station  block. 

The  station-slop  speed  (30  m/sec  in  the  sample  layout  of  Figure  1 .1 )  is  specified 
for  each  station  block  when  a  layout  is  created. 

Observe  that  the  station-stop  indicator  automatically  goes  off  as  soon  as  a 
station  stop  begins. 

Allow  Train  1  to  complete  a  station  stop. 

Unlike  emergency  stops,  it  is  possible  to  abort  a  station  stop  by  changing 
the  throttle  value  for  ^he  train  involved.  If  a  station  stop  is  aborted,  then  no 
station  stop  is  performed  until  the  three  station-stop  conditions  are  again  met 
oil  entry  into  a  station  block, 

A  train's  direction  can  only  be  changed  when  that  train  is  slopped. 
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Click  oil  Train  I's  Reverse  pushbutton  (oncej  while  that  train  is 
stopped. 

I'l'hen  drag  that  train's  throttle  slide  bar  to  a  positive  value,  e.g.. 
j  d()  (m/sec). _ _ _ 

Train  1  wall  begin  to  move  backwards:  that  is.  the  head-end  retreats  and  the 
tail-end  advances. 

I'p  to  now.  both  trains  have  remained  in  the  Operational  state.  In  order 
to  become  acquainted  W’ith  another  train  state,  try  the  following. 

Let  Train  1  travel  (backwards)  around  the  layout  until  it  derails 
at  block  jn  8 

When  a  train  enters  a  join  block  (such  as  jn  8)  from  the  tail  terminator 
(the  one  attached  to  rg  9  in  the  sample  layout),  then  the  train  will  derail.  If  a 
train  derails,  the  state  label  for  that  train  changes  to  Derailed  and  the  train 
stops  moving. 

Trains  that  are  not  Operational  do  not  respond  to  commands.  Thus,  once  a 
train  derails,  there  is  no  way  to  set  that  train  in  motion  again,  short  of  starting 
another  simulation.  Page  35  lists  all  the  conditions  under  which  a  train  will 
derail. 


Click  on  the  pushbutton  for  switch  block  sb  14  once  so  that  the 
switch  block  changes  to  the  turned  selling. 


Drag  the  Throttle  slide  bar  for  Train  2  to  a  positive  value,  e  g.. 

30  m/sec. 

Observe  that  attempting  to  enter  a  disconnected  terminator  of  a  switch  block 
would  cause  a  train  to  derail. 

Finally,  observe  what  happens  when  trains  collide. 

Allow  Train  2  to  continue  until  it  collides  with  Train  1. 

The  state  labels  of  both  trains  involved  in  a  collision  change  to  Collided.  Hence¬ 
forth.  neither  train  will  respond  to  any  commands,  so  the  demonstration  has 
ended— in  disaster!  Fortunately,  simulated  trains  are  inexpensive  to  replace. 
Page  36  lists  all  possible  collision  conditions. 

1.1.3  Shutting  the  Programs  Down 

The  programs  that  comprise  Trainset  may  be  shut  down  by  selecting  Quit 
All  in  the  Coinmand  menu  of  the  Control  Panel  or  Vieser. 
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Exorcises 


1.  Start  a  simulation  of  the  default  layout  by  issuing  the  ts  roniniaiul.  Set 
both  trains  in  motion  around  the  track  simultaneously,  with  Tram  1  trav¬ 
elling  forward  and  Train  2  travelling  backward. 

2.  F’erform  Kxercise  1.  Then,  begin  toggling  the  setting  of  the  switch  block 
SB  14  so  that  Train  1  always  passes  through  sh  14  when  sw  14  is  straight 
and  Train  2  always  passes  through  that  switch  block  when  it  is  turned. 

Note:  This  is  not  as  easy  as  it  may  sound!  Keeping  both  trains  travelling 
along  different  paths  in  this  layout  is  a  challenge,  particularly  if  both  are 
moving  as  fast  as  possible.  Train  speed  adjustments  and  switch  block 
setting  changes  must  be  coordinated  and  must  be  issued  far  enough  m 
advance  so  that  the  trains  neither  collide  nor  occupy  a  switch  block  while 
it  changes  setting. 


1.2  How  to  Build  a  Layout  of  Blocks  and  Trains 

tsed  is  an  interactive  graphics  editor  for  defining  and  modifying  railroad  layouts. 

1.2.1  Invoking  tsed 

To  sta.  t  tsed.  enter  the  following  command, 
y,  tsed  [filename] 

The  editor  may  also  be  invoked  by  entering; 
y.  ts  -edit  [jt/ename] 

When  tsed  is  started,  two  windows  appear  on  your  display,  as  sliown  in 
Figure  1.2.  The  larger  w'indow  that  is  overlaid  with  a  grid  pattern  is  the  cam  aa 
window  (Figure  1.2a).  A  railroad  layout  can  be  created  in  the  canvas  wundow. 
The  distance  between  two  adjacent  parallel  dotted  lines  in  the  grid  is  called  a 
grid  division. 

The  smaller  window  is  called  the  tools  window  (Figure  1.2b).  It  consists  of 
twelve  icons  representing  operations  called  the  tools  that  are  available  in  tsed 
for  creating  and  modifying  blocks  and  trains.  The  tools  are  applied  u.sing  the 
mouse  operations  described  on  Page  6.  Figure  1.3  shows  the  tools  window- 
together  with  the  names  of  its  tools. 

The  tools  window  contains  one  or  more  tcjols  for  each  of  the  five  types  of 
blocks  in  Trainset.  Note  that  the  tools  window  includes  two  tools  for  creating 
switch  blocks.  The  Switch  Block  1  and  Switch  Block  2  tools  differ  in  the 
orientation  of  the  switch  block:  each  is  a  mirror  image  of  the  other.  Also,  there 
are  three  tools  for  creating  regular  blocks:  Straight  Block,  Arc  Block  1  and 
Arc  Block  2.  A  straight  block  is  a  regular  block  consisting  of  a  line  segment, 
and  an  arc  block  is  a  regular  block  consisting  of  a  circular  segment .  Arc  Block  1 
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Figure  1.3:  Annotated  Tools  Window 
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and  Arc  Block  2  differ  only  in  tlie  radius  ol'  the  arcs  lliev  create.  The  Arc- 
Block  1  tool  creates  arcs  with  radius  two  grid  divisions,  and  the  Arc  Block  2 
tool  creates  arcs  witli  radius  four  grid  divi.sions. 

The  remainder  of  this  section  is  a  two-part  tutorial  on  using  tsed  for  creating 
and  editing  railroad  layouts  Section  1,2.2  introduces  you  to  the  various  tsed 
tools.  A  series  of  exercises  demonstrates  liovv  to  construct  a  layout  and  how  to 
make  simple  editing  changes.  Section  1 .2 dl  explains  how  to  set  attributes  such 
as  block  speed  limits,  how  to  save  a  layout  in  a  file,  and  how  to  exit  from  the 
editor. 

1.2.2  Using  the  tsed  tools 

The;  Current  Tool 

In  tsed.  one  tool  is  enabled  at  any  given  time,  it  is  called  the  current  tool.  The 
current  tool  is  indicated  in  the  tools  window  by  being  highlighted.  The  message 
area  at  the  bottom  of  the  canvas  window  al.so  displays  the  name  of  the  current 
tool.  On  startup.  Select  is  the  current  tool. 

Click  on  a  tool  icon  other  than  Select  to  choose  a  different  current 

tool.  Repeat  one  or  more  times. 


Regular  and  Station  Block.s 

Straight  regular  blocks  and  station  blocks  are  created  in  a  layout  by  dragging 
with  the  mouse  from  one  point  to  another  in  the  canva-s  window  when  the 
corresponding  straight  block  or  station  block  is  the  current  tool.  This  procedure 
creates  a  line  segment  between  the  starting  and  stopping  points  of  the  drag 
operation.  The  starting  point  is  called  the  head  terminator  the  block,  and 
the  stopping  point  is  called  the  tail  terminator. 


Click  on  the  Straight  Block  tool  icon. 


('reate  a  horizontal  regular  block  by  dragging  from  right  to  left 
[starting  near  the  middle  of  the  canvas  window,  as  shown  in  Fig- 
i  lire  1.4a. _ 

.411  linear  blocks  (Straight  and  Station)  created  by  tsed  arc  constrained 
to  be,  vertical,  horizontal  or  at  a  ±45°  diagonal.  To  aid  in  alignment,  tsed 
enforces  additional  constraints  on  the  placement  and  length  of  a  block  relative 
to  the  dimensions  of  the  canvas  window  grid. 

[(’lick  on  the  Station  Block  tool  icon. 
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VVlieii  a  tiew  block  is  created,  tsed  establislies  a  connection  with  an  e.xisting 
block  if  tlie  new  head  terminator  is  within  a  few  pixels  of  an  existing  terminator, 
tsed  also  constrains  the  slope  of  the  new  block  to  match  the  slojie  of  the  existing 
block  at  that  terminator. 

Station  blocks  and  straight  regular  blocks  appear  graphically  to  be  identical 
except  for  their  labels.  Regular  blocks  (whether  straight  or  arc)  are  labelled  rg. 
and  station  blocks  are  labelled  st 

The  Erase  and  Srloet  tools  are  ii.sed  for  modifying  objects  already  on  the 
canvas  window.  Erase  enables  you  to  remove  a  block  or  train  that  yon  have 
created.  Soloct  enables  you  tcj  reposition  tlie  label  for  a  block  or  to  designate 
a  block  whose  attributes  you  wish  to  change, 

I  Click  oil  the  Eras«i  tool  icon. _ _ _ 

I  Now,  erase  the  straight  block  by  clicking  on  it. 


i  Click  on  the  Sriloct  tool  icon. 
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I  Now  drag  the  label  for  the  station  block  to  a  new  position  above 
I  the  block. _ 

The  result  of  these  changes  are  shown  in  f  igure  1.4c. 

Arc  blocks  are  created  by  dragging  when  the  current  tool  is  Arc  Block  1  or 
Arc  Block  2.  The  starting  point  of  the  drag  operation  deterniines  the  location 
of  the  arc  block's  head  terminator.  The  extent  of  the  arc  is  determined  by  the 
ending  point  of  the  drag  operation  and  depends  on  the  location  of  the  head 
terminator  and.  if  the  arc  block  is  attached  to  another  block,  the  slope  of  that 
block. 

I  Click  on  the  Arc  Block  1  tool  icon. _ 

Create  an  arc  block  connected  to  the  station  block  by  dragging 
from  the  left  endpoint  of  the  station  block  toward  a  point  that 
produces  a  90'^  arc  pointing  downward,  as  shown  in  Figure  1.4d. 


When  using  the  Straight  Block.  Station  Block.  Arc  Block  1  or  Arc 
Block  2  tools,  you  can  cancel  creation  of  a  block  after  a  drag  operation  has 
already  been  initiated  by  finishing  that  drag  operation  within  a  few  pixels  of  its 
starting  point. 

Start  dragging  to  create  another  arc  block  connected  to  the  last 
arc  block,  then  cancel  the  creation  of  a  new  block  by  finishing  that 
drag  operation  at  its  starting  point. 


Iconic  Blocks:  Crosses,  Joins  and  Switches 

The  Cross  Block.  Join  Block,  Switch  Block  1  and  Switch  Block  2  tools 
always  create  blocks  that  have  a  fixed  size  and  shape.  In  tsed.  these  blocks  are 
referred  to  as  iconic  blocks.  They  are  created  by  clicking  with  the  mouse  rather 
than  by  dragging. 

When  an  iconic-block  tool  is  current  and  the  mouse  cursor  is  in  the  canvas 
window,  the  cursor  takes  the  form  of  the  icon  for  the  current  tool.  Along 
the  outer  circle  of  such  a  cursor  are  enlarged  points  called  hot  spots  at  which 
connections  with  other  blocks  can  be  made. 

Click  on  the  Join  Block  tool  icon.  Observe  that  the  mouse  cursor 
changes  to  the  form  of  a  join  block  whenever  the  cursor  is  in  the 
canvas  window. 


Position  the  rnou.se  cursor  so  that  the  hot  spot  at  its  right  head 
is  over  the  unattached  terminator  of  the  arc  block.  This  requires 
slight  overlapjiing  between  the  arc  block  and  the  join-block  cursor: 
see  Figure  1.5a. 
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(a)  Before  Clicking 


(b)  After  Clicking 


figure  1.5;  Join  Block  Creation 


j  Now  click  with  the  mouse  and  create  the  join  block  of  Figure  1.5b. 

Note  that  the  newly  created  join  block  is  coii.st rained  .so  that  the  slope  of  the 
join  block  and  the  slope  of  the  arc  block  agree  at  their  common  terminator. 

tsed  does  not  tnake  more  than  one  connection  when  an  iconic  block  is  cre¬ 
ated.  'rhus,  during  an  editing  se.ssion.  it  is  probably  best  to  create  iconic  blocks 
before  creating  the  regular  and  station  blocks  they  are  attached  to. 

'I’he  Rotate  tool  etiables  you  to  rotate  an  iconic  block  clockwise  by  one  hot 
spot. 

Click  on  the  Rotate  tool  icon. 


Now  click  on  the  join  block  created  in  step  15.  Observe  that  the 
Join  block  labelled  jn  4  rotates  so  that  its  tail  terminator  becomes 
tlip  terminator  attached  to  the  arc  block. 


Click  on  the  join  block  a  second  time  to  rotate  again. 


If  an  iconic  block  is  not  connected  to  any  other  block,  the  Rotate  tool 
rotates  it  by  one-eighth  turns.  If  a  switch  block  is  rotated  through  a  full  circle 
using  the  Rotate  tool,  it  changes  orientation. 

Trains 

A  train  may  he  created  in  a  layout  by  dragging  when  Train  is  the  current 
tool.  The  drag  operation  begins  at  the  position  desired  for  tlie  head  end  of  a 
train,  continues  along  the  blocks  to  be  occupied  by  that  train,  and  stops  at  the 
position  desired  for  that  train's  tail  end.  The  head  end  of  a  train  is  indicated 
in  the  layout  by  an  angle  bracket,  and  the  tail  end  is  indicated  by  a  square 
bracket.  All  blocks  occupied  by  a  train  are  highlighted.  'Phe  head  end  of  a  train 
is  constrained  by  tsed  to  start  in  a  regular  or  station  block. 
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(a)  Before  Train  Creation 


(b)  After  Train  Creation 

Figure  1  fi;  Oval  Layout 


16 


i  Erase  all  blocks  rurrenlly  oi>  the  layout.  'I'lien.  create  an  oval 
layout  as  in  Figure  1.6a  rriade  of  four  straight  blocks  and  four  arc 
blocks,  using  the  Straight  Block  and  Arc  Block  1  tools 

It  is  not  necessary  that  the  block  identifiers,  i.e..  the  ininbers  in  the  labels, 
match  those  in  Figure  1.6a. 

I  Click  on  the  Train  tool  icon. 

Create  a  train  on  the  oval  by  dragging  clockwise  from  the  point 
marked  A  to  that  marked  B  in  Figure  1.6a,  resulting  in  Fig- 
iire  1.6b.  _ 

If,  while  creating  a  train^  you  drag  across  the  starting  point,  the  brackets 
that  indicate  train  ends  reverse  their  directions.  Also,  observe  that  a  whole 
block  is  higlilighted  if  any  part  of  that  block  is  occupied  by  a  train. 

V'ou  should  now  feel  comfortable  with  the  basic  drag  and  click  operations 
for  creating  blocks  and  trains  in  a  layout.  In  the  next  part  of  this  tsed  tutorial, 
you  will  learn  how  to  store  a  layout  in  a  file,  how  to  specify  attributes  such  as 
speed  limits  for  individual  blocks,  and  how  to  exit  tsed. 

If  you  would  prefer  to  return  to  this  tutorial  at  a  later  time,  select  Quif^ 
from  the  File  menu  now,  and  invoke  tsed  again  when  you  are  ready  for  the 
remainder  of  the  tutorial.  There  is  no  need  to  save  your  present  work,  since  it 
will  not  be  used  in  the  second  part  of  the  tutorial. 

1.2.3  Creating  a  figure-eight  layout  file 

Our  goal  is  to  create  the  figure-eight  layout  illustrated  in  Figure  1.7  and  then 
save  that  layout  in  a  file  raylayout.l.  All  blocks  in  the  layout  should  have 
minimum  speed  of  0  (m/sec)  and  maximum  speed  of  70.  except  that  the  station 
blocks  at  the  top  and  bottom  of  the  layout  are  to  have  minimum  speed  of  0  and 
maximum  speed  of  nO. 

Select  New  from  the  File  menu.  If  you  are  continuing  from  the  first 
part  of  the  tutorial,  tsed  will  ask  if  you  wish  to  discard  changes 
in  the  canvas  window:  click  on  the  Yes  button.  In  response  to  the 
prompt,  enter  mylayout  a.«i  the  name  of  the  file  to  be  created. 

By  invoking  the  New  command  above,  mylayout.  1  becomes  the  currenl  fdr 
name.  This  name  is  indicated  in  the  title  for  the  canvas  wdiidow.  Prior  to  the 
New  command  there  was  no  current  file  name.  When  naming  a  file,  the  extension 
.1  is  automatically  appended  by  tsed  if  you  do  not  include  it,  F^atlinames  that 

^Quit  will  be  discussed  in  detail  on  Page  21. 


Figure  1.7;  A  figi. re-eight  layout 
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Figure  1.8:  Change  Default  Block  Attributes  siihvvuuJow 

do  not  begin  with  a  slash  '/'  are  interpreted  relative  to  the  current  working 
directory, 

rhe  default  tiiituniutn  and  rna.xiiiiiiin  speeds  for  blocks  can  lie  changed  by 
choosing  the  Change  Default  Block  Attributes  entry  from  the  Customize 
menu.  A  changed  default  value  applies  to  blocks  created  after  the  change:  it 
does  not  affect  blocks  already  created.  Change  Default  Block  Attributes  is 
Itself  a  menu  whose  subenlries  are  the  various  block  types. 


Idle  steps  above  change  the  default  maximum  speed  for  straight  blocks  only 
\\>  also  need  arc  blocks  and  cross  blocks  that  have  a  maximum  speed  of  70 
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Change  the  default  niaxuuuni speed  to  70  for  are  blocks,  using  the 
Arc  subentry  it)  the  Change  Default  Block  Attributes  menu 
under  Customize  and  proceeding  as  above. 

I  Also  change  the  default  rtiaxitnum  speed  to  70  for  cross  blocks. 

\’ou  are  now  ready  to  create  the  blocks  of  your  layout.  Hefer  to  Figure  17 
for  illustration  of  the  steps  below. 

j  Create  a  cross  block  near  the  center  of  the  layout  at  an  intersection 
I  point  of  two  perpendicular  dotted  lines  in  the  grid. 


Rotate  the  new  cross  block  once  using  the  Rotate;  tool.  The 
subblocks  of  the  cross  should  form  an  'x'  as  opposed  to  a  +' 


Create  two  straight  blocks  of  exactly  the  same  length,  each  form¬ 
ing  the  diagonal  of  a  square  with  sides  about  4  grid  divisions  long, 
so  that  the  head  terminators  of  the  straight  blocks  are  attached 
to  the  upper  hot  spots  of  the  cross  block. 

Note  that  the  grid  assists  you  in  determining  when  blocks  have  exactly  the 
same  length. 

Create  two  arc  blocks  with  135°  extent  and  head  terminators  at¬ 
tached  to  the  straight  blocks  that  you  just  created. 


Create  a  station  block  that  connects  to  both  unattached  termina- 
I  tors  of  the  arc  blocks. _ 

The  attributes  of  an  individual  block  may  be  customized  by  selecting  that 
block  with  the  Select  tool  and  choosing  Change  Block  Attributes  from  the 
Customize  menu. 

Click  on  the  Select  tool  icon.  I 


Click  on  station  block  st  7  in  the  canvas  window  to  select  it  for 
customization. 


Choose  Change  Block  Attributes  from  the  Customize  menu. 


In  the  subwindow  that  appears,  set  a  new  maximum  speed  by 
dragging  the  slide  bar  in  the  middle  to  50. 

d’he  station  stop  speed  is  another  attribute  that  may  be  adjusted  for  station 
blocks  using  Change  Block  Attributes.  (See  Section  2.2.5  for  a  discussion  of 
the  station  stop  speed.)  will  leave  the  default  value  at  30  for  this  layout 


20 


Create  the  lower  portion  of  a  figure-eiglil  layout  using  a  procedure 
similar  to  the  previous  seven  steps. 

j  Place  a  train  on  the  figure-eight  layout 

You  have  now  created  the  desired  figure-eight  layout.  It  is  time  to  save  your 
work  and  exit  from  the  editor. 


Save  the  figure-eight  layout  by  choosing  Save  from  the  File  menu. 

Either  the  Save  entry  or  the  Save  as  . . .  entry  in  the  File  menu  may  be 
used  to  save  your  work  in  a  file.  The  difference  is  that  Save  as  . . .  alw'ays 
prompts  you  for  a  file  name,  while  Save  uses  tlie  current  file  name  if  there  is 
one. 

Finally,  end  the  editing  session: 

Exit  tsed  by  choosing  Quit  from  the  File  menu. 

The  Quit  command  checks  for  any  unsaved  changes  before  exiting.  If  any 
are  found.  Quit  gives  you  the  option  of  writing  them  to  a  file  first.  The  Close 
command  is  similar  to  Quit,  except  tsed  does  not  exit  after  checking  for  unsaved 
changes.  Instead,  a  Close  causes  tsed  to  enter  a  state  with  an  empty  canvas 
window  and  no  current  filename. 


1.3  How  to  Run  a  Layout 

A  railroad  layout  my  layout  created  using  tsed  can  be  simulated  by  issuing  the 
follow'ing  command. 

*/.  ts  -layout  mylayout 

A  Trainset  .simulation  will  start  and  search  for  a  file  called  mylayout  .1,  first 
searching  in  the  current  working  directory,  then  in  the  standard  location  for 
layouts,  as  explained  in  the  manual  page  for  ts  in  Appendix  D. 


1.4  Control  Programs 

The  Automatic  Control  Interface  (ACI)  is  a  library  of  procedures  and  data 
structure  definitions  for  writing  programs  that  control  a  Trainset  railroad. 

The  principal  data  type  associated  with  the  ACI.  LayoutData.  represents 
various  attributes  of  the  blocks  and  trains  in  a  railroad  layout,  LayoutData  is 
described  in  Section  li.2  and  defined  in  Appendix  B.l. 

The  ACI  routines  may  be  classified  into  five  categories. 
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1  The  ACI  GetDownload  procedure  establishes  a  network  cutmection  with  a 
running  railroad  simulator  and  receives  a  report  of  the  state  of  the  railroad 
being  simulated.  GetDosnload  returns  a  pointer  to  an  internally  allocated 
data  structure  of  type  LayoutData  holding  the  state  information  that  has 
been  received.  See  Section  3.2  for  further  details. 

2.  ACI  commands  enable  a  program  to  change  certain  attributes  of  blocks 
and  trains.  Seven  command  types  are  available. 

•  SetSsitch  initiates  a  setting  change  for  a  switch  block. 

•  Accelerate  and  Decelerate  initiate  changing  the  speed  of  a  train 
at  a  constant  rate  for  a  specified  time  period. 

•  SetSpeed  initiates  changing  the  speed  of  a  train  towards  a  specified 
goal  speed 

•  SetDirection  changes  the  direction  of  a  train  that  is  slopped. 

•  EmergencyStop  halts  a  train  using  a  deceleration  rate  that  is  quicker 
than  the  rate  for  Decelerate, 

•  StationStop  enables  a  train  to  come  to  a  complete  stop  at  a  known 
location  in  a  station  block,  provided  that  the  train  enters  that  station 
block  slowly  enough. 

See  Section  3.3  for  more  details  about  ACI  commands 

3.  ACI  queries  enable  a  control  program  to  obtain  stale  information  about  a 
railroad  after  a  download  has  been  received.  Four  query  types  are  avail¬ 
able. 

•  GetBlockOccupancy  indicates  whether  a  specified  block  is  occupied. 

•  GetSwitchPosit  returns  the  setting  of  a  switch  block. 

•  GetTrainStatus  indicates  whether  a  train  is  operational. 

•  GetTrainMotion  indicates  whether  a  train  is  moving. 

See  Section  3.4  for  more  information. 

4.  ACI  voting  service  procedures.  SetSeqHumber  and  NesSeqHunber.  interact 
with  a  command  arbitration  facility  in  the  simulator.  This  service  is  useful 
when  implementing  fault-tolerant  control  programs.  S'^e  Section  3.5. 

5.  ACI  utility  procedures.  InitTimer.  GetTimer.  AwaitTimer.  CancelTimer 
and  Sleep,  provide  high-level  general  purpose  timing  facilities.  See  Sec¬ 
tion  3.6. 
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/»  demo.c  —  simple  demonstration  of  the  ACI  */ 

#include  "aci.h"  /•  ACI  definitions  and  declarations  */ 

#define  HAX.HQSTSAME  100 

#define  PQLLING.INTERVAL  0.100  /*  Seconds  */ 

#define  POLLING_TIMEOUT  200.0  /♦  Seconds  */ 

#define  FULL  (void  *)  0  /♦  generic  null  pointer  */ 

int  poll_timeout_flag  =  0;  /•  flag  for  terminating  polling  loops  »/ 

/««4c******4>«**4'«  ******»«*««»***  4'*«***4>**«»**«***««**«*»»*4i**»***»««4>«*«**«** 

*  set_poll_timeout_f lag  is  executed  by  a  timer  that  is  used  to  prevent 

*  infinite  polling  loops. 

void 

set_poll_timeout_flag() 

< 

poll_timeout_f lag++ ; 

} 

* 

*  This  program  shows  the  mechanics  of  the  ACI  layer  of  the  control 

*  program  interface,  by  initiating  a  connection  with  the  simulator, 

*  receiving  the  state  of  the  railroad,  moving  a  train,  and  making  some 

*  queries. 

mainCargc,  argv) 
int  argc; 
char  *argv  []  ; 

< 

char  *progname;  /*  name  of  this  program  ♦/ 

char  *hostname  =  /*  host  that  is  running  simulator  */ 

int  simnum  =0;  /*  distinguishes  between  simulators  running  on  same  host  */ 

Seconds  timeout  =20.0;  /*  maximum  second  to  connect  to  simulator  */ 

LayoutData  ♦datap;  /•  pointer  to  entire  received  railroad  state  info  ♦/ 

Figure  1.9:  demo.c.  an  example  using  the  ACI  (beginning). 
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TrainData  •tp;  I*  pointers  to  parts  ol  received  layout  data  */ 
BlockData  ♦bp; 

int  T=l,  B=l:  /*  identifiers  of  a  train  and  a  block  */ 
enua  Occupancy  occ;  /*  return  values  from  queries  */ 
enum  TrainMotion  tm; 
int  n;  /*  loop  counter  ♦/ 


/* 

*  Collect  command  line  args 

*/ 

progname  =  *argv++; 
if  (argc) 

hostname  =  *argv++; 
if  (argc) 

simnum  =  atoi (*argv++) ; 
if  (argc) 

timeout  =  atof (♦argv+t) ; 


0 


0 


/• 

*  Connect  and  get  the  state  of  the  railroad. 

*  Then,  use  received  values  to  check  the  identifiers  T  and  B. 

*/ 

datap  =  GetDovnloadChostname,  simnum,  progname,  timeout); 
if  (datap  ==  (LayoutData  •)  0)  •{ 
printf ("couldn’t  get  initial  download ! \n" ) ; 
exit  (1); 


if  (T  <=  1  I  I  T  >=  datap->train_ct) 
printf  ("sample  train  ID  '/A  out  of 
exit  (1); 

> 

if  (B  <=  1  1 1  B  >=  datap- >block_ct) 
printf  ("sample  block  ID  */,d  out  of 
exit  (1); 

} 


range  [l .  .’/,d]  !  \n" ,  T,  datap->train_ct) ; 

< 

range  [1 .  .’/.d]  !  \n" ,  B,  datap->block_ct) ; 


Kigure  1,9;  demo.c.  an  example  using  the  A('l  (continued). 
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/* 

*  Print  some  sample  values . 

•/ 

printf  ("Humber  ot  trains;  ‘/.d,  Humber  of  blocks;  */,d\n" , 
datap->train_ct ,  datap->block_ct) ; 

tp  =  ftdatap->trains [T] ; 

printl(''Train  '/,d  has  length  %.21,  with  front  at  block  */,d  offset  */, .2f\n“, 
[T]  tp->length,  tp->front .block,  tp->front . off set) ; 

bp  =  ftdatap->blocks [B] ; 

printf  ("Block  '/,d  has  length  .2f,  max  speed  '/.  ■2f  and  min  speed  */.  .2f\n", 
bp->length,  bp->max_speed,  bp->min_speed) ; 
if  (bp->type  ==  BT.REGULAR) 

printf  ("This  is  a  regular  block,  connected  to  blocks  ’/.d  amd  */,d\n\n", 
[i~|  bp->t.rg.tail,  bp->t  .rg  .head) ; 

/* 

*  Perform  some  accelerations  and  decelerations  of  train  T. 

•/ 

printf ("beginning  accelerationXn") ; 

[T]  Accelerated,  20.0); 

printf ("pausing. . .\n"); 

[IFI  Sleep(25.0): 

printf ("beginning  deceleration\n") ; 

1 1 1  I  Decelerated,  6.0); 

/* 

*  Travel  until  block  B  is  occupied  (or  timeout  occurs) 

*/ 

printf  ("polling  until  block  y.d  is  reached. ..  \n" ,  B); 
poll_tiraeout_flag  =  0; 

InitTimer(POLLIHG_TIMEOUT,  0,  set_poll_timeout_flag) ; 


12. 13  while  ((occ  =  GetBlockOccupancy(B) )  ==  0C_FBEE  ftA  !poll_timeout_f lag) 

Sleep(P0LLIHG_IHTERVAL) ; 


Figure  1.0:  demo.c.  an  example  using  the  ACI  (rontinued). 
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if  (occ  ==  OC.ERRQR)  i 

printf ("error  getting  block  occupancy !\n") ; 
exit  (1); 

> 

if  (poll_timeout_f lag)  { 

printf  ("polling  timed  out  after  'l,t  secondsXn",  P0LLIlIG_TIME0in') ; 
exit  (1); 

} 

CancelTimerO ; 

/*  assertion;  occ  ==  0C_0CCUPIED  ♦/ 

/* 

♦  Perform  an  emergency  stop,  tben  poll  until  train  stops 

•/ 
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printf ("performing  emergency  stopXn"); 

EmergencyStop(T) ; 

printf ("polling  until  train  stops ... \n” ) ; 
poll_timeout_flag  =  0; 

Inittimer(POLLISG_TIMEQUT,  0,  set_poll_timeout_flag) ; 

while  ((tm  =  GetTrainMotion(T) )  ==  TH_M0VING  !poll_timeout_f lag) 
Sleep(POLLIIIG_IHTERVAL) ; 

if  (tm  ==  TM.ERROR)  { 

printf ("error  when  querying  about  train  motionlNn"); 
exit  (1); 

} 

if  (poll_timeout_f lag)  < 

printf  ("polling  timed  out  after  '/,f  secondsXn",  P0LLIHG_TIME0UT) ; 
exit  (1); 

} 

CancelTimerO ; 

/♦  assertion:  tm  ==  TM.STOPPED  */ 


printf ("train  has  stopped. \n") ; 
exit  (0): 


Figure  1.9:  demo.c,  an  e.xample  using  the  .4Cl  (concluded). 
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'[’iie  example  program  demo.c  (see  Figure  i.9)  illustrates  the  use  of  the  AC'l. 
riiis  program  rormects  to  a  simulation  and  receives  the  state  of  a  railroad,  tlien 
attempts  to  move  a  train  in  that  railroad  to  a  certain  block  and  perform  an 
emergency  stop.  Some  key  points  about  the  code  are  indicated  by  numbers  [^, 
[Tj.  etc. 

pTj  d'he  include  file  aci.b  contains  declarations  and  definitions  required  for 
compiling  a  source  file  that  uses  the  ACI.  In  order  to  create  an  executable, 
one  must  link  with  the  ACI  library  libaci.a. 


[T]  Time  values  passed  to  the  A(T  timer  procedures  are  always  floating-point 
quantities  repre.senting  seconds.  An  ACI  type  Seconds  is  defined  for  such 
quantities. 

HTj  set_polling_timeout  is  the  procedure  that  will  be  invoked  if  a  tsuser 
timer  expires.^  Such  a  procedure  cannot  be  invoked  with  arguments,  so  it 
changes  a  global  variable  polling_timeout  in  order  to  inform  the  main 
program  about  timer  expiration. 

IT]  The  file  aci.h  defines  a  number  of  data  types  besides  LayoutData.  The 
type  TrainData  is  used  to  represent  download  information  received  for  a 
train:  likewise.  BlockData  represents  download  information  for  a  block. 
Both  TrainData  and  BlockData  are  component  types  used  in  the  defini¬ 
tion  of  LayoutData.  Enumerated  types,  including  Occupancy  and  Train- 
Motion.  are  used  for  command  arguments  and  query  return  values.  Trains 
and  blocks  have  unique  positive  integer  identifiers. 

|T~|  GetDosmload  takes  four  arguments,  returns  a  null  pointer  on  failure,  etc. 
Chapter  3  is  the  reference  for  this  and  the  other  ACH  procedures. 
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Several  examples  of  references  to  a  LayoutData  structure  follow  the  invo¬ 
cation  of  GetDownload.  More  direct  references  such  as 


datap->trains [T-l] . length 
datap->blocks CB-I] .t.rg.tail 


could  be  used  in  place  of  those  that  involve  tp  and  bp  in  demo.c.  Observe 
that  the  index  of  a  train  in  datap'>trains  is  always  one  less  than  that 
train's  identifier.  A  similar  remark  holds  for  blocks. 

The  function  PrintDosnload  in  Appendix  B.2  includes  examples  of  refer¬ 
ences  to  every  component  in  a  LayoutData  structure. 

Checking  the  values  of  T  and  B  at  is  not  strictly  necessary  in  this 

program,  since  their  values  are  known  to  be  valid  in  this  case.  It  is  a 
good  defensive  programming  practice  to  include  such  checks  anyway,  as 
protection  against  future  changes 

*.Vole:  As  explained  in  Section  .'J.e.  a  call  to  InitTitnsr overrides  any  prior  calls.  Thus,  we 
speak  of  “the  ACT  timer,"  because  only  one  such  timer  can  be  in  efTcct  at  any  lime. 


jV[  ACl  coniinandissuch  as  Accelerate  are  iion-blorkiiig  and  return  no  vrdues. 
They  print  no  warnings  about  unreasonable  arguments.  The  command 


Accelerated,  20.0); 


requests  that  train  T  accelerate  for  a  duration  of  20  seconds,  increasing  its 
speed  during  that  period  at  the  predefined  fixed  acceleration. 


;  10.11 
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The  instruction 


Sleep(25.0); 


causes  demo.c  {not  the  Trainset  simulator!)  to  suspend  e.xecution  for  25 
sec.  This  is  long  enough  that  the  subsequent  Decelerate  command  1 1 1 1 
is  unlikely  to  interfere  with  the  prior  Accelerate  cotnmandj^. 

The  train  would  begin  to  reduce  its  speed  as  soon  as  the  Decelerate 
command  is  received,  even  if  the  prior  acceleration  had  not  been  in  effect 
for  the  acceleration’s  entire  duration.  For  example,  if  the  Sleep  had  been 
for  10  seconds  instead  of  25.  then  train  T  would  accelerate  for  about  10 
seconds,  then  decelerate  for  5  seconds. 


The  query  GetBlockOccupancy  is  used  so  that  train  T  may  reach  block 
B  That  query  is  issued  frequently  until  block  B  is  found  to  be  occupied 
or  until  an  error  or  timeout  occurs.  This  technique  of  frequent  querying 
is  called  polling.  The  ACI  timer  is  set  up  before  the  while  statement  to 
provide  timeout  mechanism  for  leaving  that  loop. 

I  13  I  'file  loop  guard  condition  shows  that  there  are  two  ways  to  leave  the  loop. 


•  If  occ  differs  from  0C_FREE,  i.e..  occ  has  value  0C_0CCUPIED  or 
OC.ERROR.  then  the  loop  will  be  exited.  (Query  errors  can  be  caused 
by  invalid  arguments,  loss  of  communication  with  the  railroad,  etc.) 

•  If  polling_timeout  has  a  non-zero  value,  then  the  loop  will  be  ex¬ 
ited.  polling_tiineout  changes  from  zero  to  a  non-zero  value  if  the 
timer  expires  (.see  and  the  invocation  of  InitTimer). 


t  I'l.lS.lG 


Before  concluding  that  occ  =  0C_0CCUPIED,  which  would  indicate  occu¬ 
pancy  of  block  B,  it  is  necessary  to  eliminate  the  other  events  that  can 
cause  the  loop  to  exit. 


j  17  I  A  period  of  time  elapses  between  the  moment  that  block  B  becomes  oc¬ 
cupied  and  the  time  when  the  control  program  demo.c  can  act  on  that 
information.  This  time  period  ari.ses  from  the  following  causes. 


•  Delay  from  polling.  Some  time  necessarily  elap.ses  between  the 
moment  that  block  B  becomes  occupied  and  the  time  when  that  sen¬ 
sor  is  checked.  The  sensor  is  checked  by  each  successful  call  to  the 
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query  GetBlockOccupancy.  Thus,  if  GetBlockOccupancy  succeeds 
this  period  is  bounded  by  the  execution  time  of  one  iteration  of  the 
polling  loop,  except  possibly  when  block  B  is  found  to  be  occupied 
on  the  first  GetBlockOccupancy  query. 

•  Network  delay.  This  is  the  time  required  for  a  sensor  value  to  be 
communicated  to  the  control  program. 

•  Local  processing  delay.  Once  the  process  that  is  running  demo.c 
receives  a  communication  that  block  B  was  occupied,  several  further 
steps  occur;  the  query  function  returns:  the  polling  loop  exits:  cliecks 
are  performed  in  order  to  deduce  that  block  occupancy  was  in  fact 
the  reason  for  loop  exit;  and  the  timer  is  cancelled.  Kach  of  these 
steps  requires  local  processing  time. 


Such  delays  can  affect  the  correctness  of  control  programs.  For  example, 
the  occupancy  of  a  block  might  change  by  the  time  that  a  control  program 
could  take  action  on  that  occupancy  information.  In  particular,  it  is  not 
correct  to  conclude  that  block  B  is  currently  occupied  based  solely  on  the 
fact  that  occ  has  the  value  OC.OCCUPIED  at  1 17 1. 

f  18  I  The  command  EmergencyStop  causes  a  train  to  reduce  its  speed  to  zero 
quickly.  Unlike  Accelerate  and  Decelerate,  the  effects  of  EmergencyStop 
cannot  be  interrupted  by  another  command. 
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Polling  with  the  query  GetTrainMotion  is  used  in  demo.c  to  determine 
when  the  train  has  come  to  a  complete  stop. 


Exercises 


1.  Write  a  program  that  uses  the  ACI  to  cause  both  trains  in  the  sample 
layout  (see  Figure  1.1)  to  move  around  the  track  for  five  minutes,  then 
stop.  (Compare  to  Exercise  1  of  Section  1.1.2.)  The  trains  need  not  travel 
on  different  loops. 


2.  As  in  the  loop  12  ,  a  timer  is  set  up  just  before  the  while  statement 
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in  order  to  guard  against  an  infinite  loop.  Is  this  timer  necessary,  or  is 
that  loop  certain  to  exit  in  a  reasonable  amount  of  time  without  a  timer? 
(Hint;  Consider  the  specifications  of  GetTrainMotion  in  Section  3.4.4.) 


Chapter  2 

Trainset  Railroads 


2.1  Introduction 

Trainset  railroads  are  idealized  versions  of  real  railroads.  This  chapter  dis¬ 
cusses  the  attributes  and  operation  of  Trainset  railroads,  ^'ou  will  see  that 
while  Trainset  railroads  are  simpler  than  their  real-life  counterparts,  the  sim¬ 
plifications  are  ones  that  do  not  make  it  appreciably  easier  to  write  programs 
to  control  the  railroad, 

2.2  Blocks 

In  a  Trainset  railroad,  a  layout  cotisists  of  an  assembly  of  blocks  together  with 
movable  /rrtin.'<  that  occupy  some  of  those  blocks.  See  Figure  1.1  for  an  example. 

Fvery  block  is  assigned  a  unique  block  II)  U,  a  Itogth  iy.  a  rnaiimmv  speed 
Itmtl  MXy  and  a  mtnimum  speed  limit  M.\y.  VVe  expect’ 

0  <  MNy  <  MXy  <  MAX  FLOAT. 

Kach  block  has  a  set  of  te;rminiitors  that  delimit  the  track  implementing  that 
block. 

As  in  real  railroads,  each  block  has  an  associated  .sensor  called  a  track  circutl, 
that  indicates  whether  that  block  is  occupied  by  a  train.  Polling  a  track  circuit 
only  returns  one  bit  of  information  signifying  whether  the  associated  track  block 
is  occupied.  Note  that  it  is  not  possible  to  learn  the  exact  location  of  a  moving 
train  from  the  information  returned  by  a  track  circuit. 

A  block  may  have  between  two  and  four  terminators,  depending  on  its  type. 
I'liere  are  five  types  of  train  blocks:  regular,  join,  switch,  cross  and  station 
blocks.  These  are  illustrated  in  Figures  21  2. .a. 

'  MAX  FLO  AT  is  I  ho  largest  floating  point  number  on  the  computer  system.  The  standard 
mks  units  of  mcasurf  arc  used  throuj^houl  this  document. 
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Figure  2.1:  Regular  Blocks 


Two  blocks  are  attached  to  each  other  if  each  of  the  blocks  has  a  terminator 
that  IS  associated  with  the  other  block.  Trainset  block  layouts  are  subject  to 
the  following  restrictions. 

•  A  terminator  may  be  associated  with  at  most  one  block. 

•  A  block  may  not  be  attached  to  it.self. 

•  Blocks  may  not  be  attached  to  each  other  tnore  than  once.  e.g..  circular 
track  configurations  that  consist  cnly  of  two  half-circle  blocks  are  prohib¬ 
ited. 

These  restrictions  make  it  simpler  to  describe  attachments  between  blocks,  but 
do  not  limit  the  topology  of  Trainset  layouts.  For  example,  we  could  easily 
construct  a  circular  track  configuration  using  two  quarter  circles  and  a  semicir¬ 
cle. 

It  is  not  necessary  that  all  terminators  of  a  block  be  attached  to  other  blocks. 
Of  course,  a  train  will  derail  if  it  attempts  to  exit  from  a  block  at  an  unattached 
terminator. 

2.2.1  Regular  Blocks 

Flach  regular  block  has  two  terminators.  Such  a  block  can  have  the  shape  of  a 
line  segment  or  a  circular  arc.  See  Figure  2.1. 

2.2.2  Join  Blocks 

A  join  block  has  three  terminators  and  allows  two  train  routes  to  merge.  Two 
of  the  terminators,  called  the  heads,  are  each  connected  to  the  third  terminator, 
called  the  tail. 

A  train  can  occupy  the  track  belw'een  either  of  the  heads  and  the  tail.  Trains 
can  enter  a  join  block  at  either  head  and  exit  through  the  tail.  A  train  derails 
when  it  either  enters  a  join  block  at  the  tail  or  leaves  from  one  of  the  heads. 
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Figure  2.2:  Join  Block 
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Figure  2..‘F  C  ross  Block 


.loin  blocks  are  assumed  to  be  mrters  long  measured  from  the  tail 

to  either  head  terminator.^  At  most  one  train  may  occupy  a  join  block  at  any 
time.  If  a  second  train  enters  a  join  block  that  is  already  occupied,  then  a 
collision  occurs. 

2.2.3  Cross  Blocks 

A  cross  block  (see  Figure  2.3)  allows  a  track  to  inter.sect  itself,  ,so  that  ‘‘figure 
eights’'  and  related  designs  may  be  built,  A  cross  ha.s  four  terminators,  and  a 
train  may  only  travel  between  any  opposing  pair  -turns  are  not  allowed.  T  hus, 
cro.ss  blocks  behave  like  two  .short  regular  blocks,  called  subblocks,  vvitli  the 

^Constants  such  as  arc  determined  at  the  time  of  installation.  See  the  installation 

manual  for  details. 
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Figure  2.4:  Switch  Block 


same  length  and  speed  limits,  that  have  been  overlaid  at  iheir  nnd[K)iuls  A 
cross  block  and  both  of  its  subblocks  are  occupied  wheiieier  either  of  those 
subblocks  is  occupied.  Cross  subblocks  are  i,E.\crosi,  meters  long  A  collision 
occurs  when  a  cross  block  becomes  occupied  by  two  or  more  trains 

In  order  to  distinguish  between  the  subblocks  of  a  cross  block,  each  has  its 
own  block  ID.  One  of  these  also  serves  as  the  cro.ss  block's  ID 

2.2.4  Switch  Blocks 

A  switch  block  (see  Figure  2.4)  has  three  terminators,  labelled  tati.  straight  head 
and  turn  head,  and  consists  of  a  movable  track  segment  that  has  settings 
and  a  mechanism  to  move  this  track  between  those  settings.  Depending  on  the 
setting  of  the  movable  track,  either  the  train  may  travel  between  the  tail  and 
straight  head  (in  either  direction)  or  between  the  tail  and  turn  head.  Thus,  a 
switch  block  can  be  part  of  two  different  train  routes,  according  to  that  switch 
block’s  setting. 

A  switching  time  must  elapse  for  a  ssvitch  block  to  change  from  one 

.setting  to  the  other.  The  swdtch  setting  is  undefined  during  this  time  period 
If  a  switch  is  commanded  to  change  to  one  setting  (e  g.,  straight)  wjiile  it  is 
already  in  that  setting  or  in  ♦he  pro<'‘»s.s  of  changing  to  that  .setting,  then  that 
setting-change  command  ha.s  no  effect.  If  the  setting-change  comniand  was  to 
switch  to  the  olher  setting,  th^n  the  switch  begins  changing  to  the  new  .setting. 
U  lakes  a  full  Iswi^ch  seconds  to  changf  to  a  new  setting,  even  if  the  switch 
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Figure  2. a:  Siation  Block 


seUing  was  undefined  at  the  time  of  the  setting  change  command. 

A  train  attempting  to  traverse  a  switch  block  will  derail  under  the  following 
circumstances. 

•  'I'he  switch  block  has  undefined  setting. 

•  A  switch  change  is  attempted  on  the  switch  block 

•  The  train  enters  the  turn  head  terminator  of  a  straight  switch,  or  the 
straight  head  terminator  of  a  turned  switch. 

Switch  blocks  are  f  TAswitcfi  meters  long  measured  from  the  tail  '.o  eitlier  of 
the  other  terminators.  At  most  one  train  rna\  occupy  a  switch  block  at  a  lime 
or  a  collision  will  occur. 

A  switch  block  that  is  occupied  uy  a  derailed  or  collided  train  will  not  respond 
to  setting  change  commands. 

2.2.5  Station  Blocks 

Station  blocks  are  like  regular  blocks  (see  Figure  2.1)  except  that  they  allow  a 
train  to  stop  at  a  fixed  specified  location,  (  sing  a  station  block  is  the  only  way 
to  be  sure  of  the  exact  position  of  a  train  after  it  has  begun  moving,  because 
track  circuits  only  reveal  whether  a  block  was  occupied  sometime  in  the  past 

Each  station  block  B  has  a  statton-stop-speed  VSS^,.  A  station  stop  begins 
whenever  a  train  that  is  in  station-stop  mode  (see  Section  2. .3)  enters  a  station 
block  while  travelling  with  speed  at  most  VSS^.  Inder  these  conditions,  the 
train  will  automatically  begin  to  slow  down  so  that  it  will  come  to  a  complete 
slop  exactly  at  the  opposite  terminator  of  the  station  block. 

A  station  stop  by  a  train  can  be  aborted  by  commanding  that  train  to  change 
velocity  or  acceleration. 
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2.3  Trains 

Every  tram  is  assigned  a  unique  Irani  ID  t  and  a  length  and  has  tiie  following 
attributes  that  may  change  during  a  simulation. 

•  A  speed  iy  and  an  acceleration  Cj.. 

•  Two  ends,  labelled  head  and  tail,  that  are  points  within  blocks. 

•  A  direction  dir.j.. 

•  An  emergency-stop  mode  es^.  and  h  station-stop  mode  s.s.^.  which  may  be 
enabled  or  disabled. 

We  expect  0  <  ^  MAXFLOAT.  The  distance  along  the  track  between  a 

train’s  ends  is  always  that  train's  length  L.J.. 

FDach  train  in  a  layout  always  occupies  a  sequence  of  attached  blocks.  A 
train  occupies  a  block  if  the  interiors  of  that  train  and  that  block  intersect.  For 
example,  suppose  that  the  train  in  Figure  2.6  has  just  completed  a  station  stop, 
so  that  one  end  of  that  train  is  at  a  terminator.  That  train  occupies  blocks 
rg  10  and  st  11,  but  does  not  occupy  block  rg  12.  If  that  train  moves  slightly 
to  the  left  (i.e..  forward),  it  will  then  occupy  block  rg  12. 

A  train's  direction  dir.^.  determines  which  of  the  two  ends  advances  if  that 
train  moves  forward.  The  train  end  that  advances  is  called  the  front,  and  the 
other  end  is  called  the  rear.  For  example,  suppose  that  the  head  of  a  train  is 
the  front.  If  that  train’s  direction  is  changed,  then  the  train's  tail  will  become 
the  front  and  the  head  will  become  the  rear.  A  train's  direction  can  only  change 
w'hen  that  train  is  not  moving,  that  is.  when  r.j.  =  0^.  =  0. 

2.3.1  Train  States 

A  train  can  be  in  one  of  three  states:  operational,  derailed  or  collided.  Figure  2,7 
shows  possible  transitions  between  these  stales. 

A  train’s  state  changes  from  operational  to  derailed  under  any  of  the  follow¬ 
ing  conditions: 
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Figure  2.7:  'I'raiti  .•state  traii.sitions. 

•  'I'liat  tram  occupies  a  block  and  the  train's  speed  r.,  violates  one  of  ilial 

block's  sjieed  limits,  r.,.  <  or  <  v.,.. 

•  The  front  of  that  train  e.xil.s  a  block  at  an  unattached  lerininator 

•  The  front  of  that  train  enters  a  join  block  at  the  tail  terminator  or  exits 
a  join  block  from  a  head  terminator. 

•  That  train  occupies  a  switch  block  that  h;is  undefined  setting. 

•  A  switch  change  is  attempted  on  a  switch  block  occupied  by  that  tram 

•  That  train  enters  the  turn  head  terminator  of  a  switch  in  the  straight 
setting  or  the  straight  head  terminator  of  a  switch  in  the  turned  setting 

A  train’s  slate  changes  to  collided  if  there  is  another  tram  in  the  layout  such 
that  either  of  the  following  conditions  holds. 

•  Both  trains  occupy  the  same  switch,  join  or  cross  block. 

•  Both  trains  occupy  the  same  block  at  the  same  point. 

2.3.2  Laws  of  Motion 

In  Trainset,  the  acceleration  of  a  train  is  one  of  the  constant  values  .‘ICf,  0. 
—  /Iff  and  — /Icmcr-  except  during  a  station  stop.  We  expert 

0  <  /Iff  <  Aemcr  <  MA  XFl,OAl  . 

If  the  acceleration  of  a  train  is  constant  during  a  time  interval  [fo,  t|]  and 
r{t,  )  is  the  speed  r.,.  of  that  train  at  time  then 

t'(li)  =  '(bi)  +  (^1  —  hi) 
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For  sijcli  a  tram,  if  j  (M  represents  the  position  of  an  end  of  tliat  train  at  lime 
t,.  then 

1 )  =  +  i  (i(i )  -  (ii  —  /q)  +  (<1  — 

A  train's  station-stop  mode  turns  on  Uie  station-stop  feature  for  tiial  train. 
A  station  stop  begins  if  the  station-stop  mode  of  a  train  is  enabled  and  that 
tram  enters  a  station  block  with  speed  satisfying 

0<  V.,  < 

where  VSS^  is  the  station-stop  speed  of  that  block.  The  station-stop  mode  of 
that  train  is  disabled  as  soon  as  a  station  stop  begins. 

A  station  stop  by  a  train  can  be  aborted  by  setting  that  train's  speed  or 
acceleration  during  that  station  stop.  If  a  train  performs  a  station  stop  in  a 
station  block  and  that  station  stop  is  not  aborted,  then  all  of  the  following  will 
hold  upon  its  completion. 

•  The  train's  speed  v^.  and  acceleration  a,  will  be  0. 

•  The  train's  front  will  be  at  the  opposite  terminator  of  that  station  block. 

•  The  train  will  occupy  that  station  block. 

A  station  stop's  completion  may  be  observed  using  the  query  GetTrainHotion 
discussed  in  Section  3.4. 

The  emergency-stop  feature  allows  a  train  to  stop  at  a  faster  rate  than 
usual.  A  train  performs  an  emergency  stop  when  its  emergency-stop  mode 
is  enabled.  During  an  emergency  stop  by  a  train  7.  its  acceleration  satisfies 
aj.  =  — -dctner-  The  emergency  stop  finishes  as  soon  as  v.^  becomes  0.  At  that 
time,  the  emergency-stop  mode  for  T  is  disabled  and  its  acceleration  becomes 
0. 

A  train  does  not  respond  to  commands  during  an  emergency  slop.  Thus, 
emergency  stops  cannot  be  aborted. 
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Chapter  3 

Automatic  Control 
Interface  (ACI) 


3.1  Introduction 

The  Control  Program  Interface  (CPI)  is  used  for  writing  computer  programs 
that  interact  with  Trainset  railroads.  It  consists  of  two  layers,  the  Automated 
Control  Interface  (ACI)  and  the  Low-Level  Interface  (LLI).  as  illustrated  in 
Figure  3.1. 

The  ACI  layer  consists  of  library  routines  that  can  be  used  in  a  control 
program  to  establish  communication  w'ilh  a  simulation  of  a  Trainset  railroad, 
obtain  the  state  of  that  railroad,  interact  with  the  railroad's  layout  using  com¬ 
mands  and  queries  and  use  the  Trainset  voting  service.’  The  ACI  also  provides 
some  local  timer  utilities.  This  layer  is  intended  to  meet  the  needs  of  most  con¬ 
trol  program  writers. 

’The  voting  service  facilitates  writing  fault- tolerant  control  programs.  See  Section  .'5..T 
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Figure  3.1;  Communication  interface  layers. 
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The  LLl  layer  has  most  of  the  same  capabilities  as  the  ACl,  but  at  a  more 
primitive  level  that  requires  a  programmer  to  manage  commiimcation  and  mes¬ 
sage  buffers  directly. 

This  chapter  describes  the  ACI  layer.  Usage  details  are  described  in  a  ref¬ 
erence  format  using  C  language  syntax.  Chapter  4  presents  the  LLl  layer 
For  programming  examples  that  use  the  ACI  layer,  see  Section  1.4  and  Ap¬ 
pendix  B.2. 

A  Trainset  railroad  can  accept  three  kinds  of  messages  from  CPI  clients 
A  state  download  request  asks  for  a  railroad’s  state.  A  command  can  affect  a 
railroad  layout,  e.g.,  by  changing  a  switch  block’s  setting  or  setting  a  train's 
acceleration.  A  query  requests  information  about  a  block  or  train. 

Trainset  railroads  silently  ignore  messages  that  contain  syntax  errors, 


3.2  Initial-State  Download 


LayoutData  ♦ 

GetDovnloadChostname,  simnum,  prognajne,  timeout) 

char  *hostname;  /*  machine  running  a  simulation  */ 
int  simnum;  /*  identifies  a  running  simulation  •/ 
char  *progname;  /•  name  of  invoking  program  */ 
double  timeout;  /*  in  seconds  */ 

Fxecuting  GetDosnload  causes  a  network  connection  to  be  established  with 
a  railroad  simulation  and  information  about  the  stale  of  the  railroad  to  be 
received  from  that  simulation.  The  download  is  stored  in  an  internal  static  data 
structure  of  type  LayoutData  defined  in  Appendix  B.l. 

hostname  and  simnum''  must  identify  an  executing  Trainset  railroad  simu¬ 
lation.  and  timeout  must  be  positive,  or  GetDownload  will  fail.  If  hostname  is 
an  empty  string,  then  the  local  host  is  u.sed. 

The  addre.ss  of  the  LayoutData  structure  is  returned  if  execution  succeeds. 
A  message  is  printed  and  a  NULL  pointer  is  returned  on  failure.  Possible  failure 
conditions  are: 

•  timeout  is  not  a  positive  floating-point  value. 

•  A  netw'ork  connection  could  not  be  established  before  timeout  seconds 
elap.sed. 

•  There  is  no  simulation  on  the  host  hostname  with  identifier  simnum. 

^sininmii  determines  which  well-known  ports  arc  to  be  used  when  initializinj; communication 
with  a  railroad  simulation.  .Multiple  railroad  simulations  may  be  run  simultaneously  on  the 
same  host  if  they  use  different  siiuiuB  values. 


•  An  error  vva.-.  delected  while  parsing  the  download. 

•  GetDowaload  has  already  been  called  successlnlly  by  this  rhein  at  a  (irior 
lime, 

'I'he  download  consists  of  the  following. 

Cleneral  parameters: 

•  The  number  of  blocks  Snocki  trains  Vj^ajui  in  the  layout.  Block 

IDs  range  from  1  to  ^'hlocks  tram  IDs  range  from  1  to 

•  riie  standard  acceleration  rate  ACY'and  emergeticy-stop  acceleration  rate 
'Umcr  for  trains. 

•  The  switching  time  T^witch  fof  switch  blocks. 

•  The  voting  window  \\\otiag  and  voting  quorum  Q^ounn  commands  to 
be  accepted.  See  Section  3.5. 

For  each  block: 

•  The  ID  B.  type  and  length  of  the  block. 

•  The  maximum  speed  limit  MX^  and  mininuini  speed  limit  MXg. 

•  The  attachments  for  that  block.  A  block  ID  is  specified  for  each  attached 
terminator  and  0  for  each  unattached  terminator. 

•  For  station  blocks,  the  station-stop  speed  VSS^. 

•  For  subblocks  of  cross  blocks,  the  block  ID  of  the  cross  block. 

For  each  train: 

•  The  ID  T  and  length  of  that  train. 

•  The  locations  of  that  train’s  head  and  tail  ends.  The  location  of  an  end 
of  a  train  is  specified  by  giving  the  ID  of  a  block  containing  that  end  and 
the  offset  of  that  end  within  the  block.  Offsets  are  measured  from  the  tail 
terminator  of  a  block. 


3.3  Commands 

A  CFI  client  can  cause  a  change  in  a  Trainset  railroad  by  is,suing  a  command. 
Such  a  change  is  called  a  layout  action.  Only  trains  and  switch  blocks  ran  be 
affected  by  commands. 
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Each  coniiiiand  gives  rise  to  at  tiiost  one  layout  action  A  cotninaiid  fails 
to  cause  a  layout  action  if  the  preconditions  of  that  coinniand  are  not  satisfied. 
For  example,  a  SetDirection  command  causes  a  new  direction  to  be  assigned 
to  a  train  only  if  that  train  is  operational  and  not  moving,  Al.so.  multiple  com¬ 
mands  may  optionally  be  required  to  cause  a  single  layout  action,  as  described 
in  Section  3.5. 

There  are  seven  types  of  command  that  a  ( ‘FI  client  can  send  to  a  Trainset 
railroad:  SetSwitch.  Accelerate.  Decelerate.  SetSpeed.  SetDirection. 
EraergencyStop  and  StationStop.  These  are  specified  as  follows. 

3.3.1  Set  Switch 

enum  HesPosit  -{NP.STRAIGHT ,  HP.TURNED}: 
void 

SetSwitchCblock.id,  nen.setting) 
int  block_id; 

enum  NevPosit  nes.setting: 

SetSwitch  causes  the  switch  block  identified  by  block.id  to  begin  changing 
setting  to  neo.setting.  A  setting  change  requires  Tswiick  seconds  to  complete. 

block.id  must  identify  an  unoccupied  switch  block  that  is  neither  in  tlie 
setting  nes.setting  nor  in  the  process  of  changing  to  that  .setting;  olherwhse 
no  action  is  taken. 

3.3.2  Accelerate  and  Decelerate 

void 

Accelerate (train_id,  duration) 
int  train_id: 
double  duration; 


void 

Decelerate(train_id,  duration) 
int  train_id; 
double  duration; 


Accelerate  and  Decelerate  cause  the  acceleration  atrain  id  of  the  train 
identified  by  train.id  to  be  assigned  the  following  value. 


f  +ACr  for  Accelerate 
I  —ACC  for  Decelerate 
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"train.id  tiie  value  0  after  either  duration  secDiids  elapse  or  the 

train's  speed  reaches  0,  wliichever  comes  first,  unles.s  (itrain  id  fhanged  again 
or  tlie  train  collides  or  derails. 

duration  must  he  non-negative,  and  train.id  must  identii'y  an  operational 
train  that  is  not  performing  an  emergency  stop:  otherwise  no  action  is  taken 

3.3.3  Set  Speed 


void 

SetSpead(train_id,  goal.speed) 
int  train.id; 
double  goal.speed; 

SetSpeed  causes  the  acceleration  utrain.id the  train  identified  hy  train.id 
to  be  a-ssigried  the  following  value. 

{+/irr  if  goal.speed  >  ctrain.id 
0  if  goal.speed  =  I'train. id 
-ACC  ifgoal_speed<  Itrain. Id 

The  acceleration  (itrain.id  a.ssigned  the  value  0  when  that  train's  sjieed 
reaches  goal.speed.  unless  ^train.id  changed  again  or  the  train  derails  or 
collides  before  the  goal  speed  can  be  reached. 

goal.speed  must  be  non-negative,  and  train.id  must  identify  an  opera¬ 
tional  train  that  is  not  performing  an  emergency  slop:  otherwise  no  action  is 
t  aken. 

3.3.4  Set  Direction 

void 

SetDirection(train.id,  nen.dir) 
int  train.id; 
int  new.dir; 

SetDirection  cau.ses  the  direction  dtrtrain.id  Irain  identified  by  train.id 
to  be  assigned  the  following  value. 

{lail-to-kead  if  nev.dir  >  0 

he.ad-lo-iail  if  nes.dir  <  0 

opposite  of  rfjftrain.id  neH.dir  =  0 

Here,  tatl-to-hfad  means  tliat  the  head  end  of  that  train  is  the  front  end.  and 
hf  ad-to-tail  means  that  tJie  tail  end  is  tlie  front  end. 
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The  direction  d)»train_id  of  train_id  must  identify  an  operatjonai  train 
that  satisfies 

"train.id  =  <train_id  d 

or  no  action  is  taken. 

3.3.5  Emergency  Stop 

void 

EmergencyStop(train_id) 
int  train_id; 

EmerfencyStop  causes  the  emergency-stop  mode  e-Hrain.id  train 

identified  by  train. id  to  be  enabled.  This  causes  an  emergency  stop  to  begin 
immediately.  That  train’s  acceleration  utrain.id  is  a.ssigned  the  value  — /lemer 
until  the  train's  speed  I'train.id  becomes  0,  at  which  time  fltrain.id*®  assigned 
the  value  0  and  entrain  id  is  disabled. 

train.id  must  identify  an  operational  train,  or  no  action  is  taken 

3.3.6  Station  Stop 

enuia  StationStopMode  {SS.DISABLED,  SS.ESABLED}; 
void 

StationStop(train_id,  new.val) 
int  train. id; 

enure  StationStopMode  new.val; 

StationStop  causes  the  station-stop  mode  s»train_id  of  train  identified 
by  train.id  to  be  assigned  new.val.  A  station  stop  (see  Section  2.3.2)  begins 
if  an  operational  train  enters  a  station  block  with  station-stop  mode  enabled 
and  with  speed  I'train  id  ^hat  does  not  exceed  the  block’s  station-stop  speed 

train.id  must  identify  an  operational  train  that  is  not  performing  an  emer¬ 
gency  stop;  otherwise  no  action  is  taken. 

3.4  Queries 

Queries  are  the  only  way  that  a  CPI  client  can  obtain  information  about  a 
layout  after  the  initial-state  download  has  been  received.  There  are  four  query- 
types:  GotBlockOccupancy. GetSwitchPosition.  GetTrainStatus  and 
GetTrainMotion.  These  queries  return  very  limited  information.  Thus,  facts 


about  the  layout's  state  such  as  a  trcun’s  speed  and  emergency-stop  mode  must 
be  computed  by  a  CiM  client  program  from  a  knowledge  of  past  values  and  of  the 
properties  of  Trains et  railroads.  This  makes  writing  process  control  program.s 
difficult  but  realistic. 

3.4.1  Block  Occupancy 

enum  Occupancy  -(OC.FREE,  OC_OCCUPIED,  0C_ERR0R  =  ”1}; 

enuia  Occupancy 
GetBlockOccupancy (block. id) 
int  block.id; 

'I'he  occupancy  status  of  the  indicated  block  is  returned.  If  block.id  is  not 
the  ID  of  a  block  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simulation. 
OC.ERROR  is  returned. 

3.4.2  Switch  Position 

enum  SwitchPosit  {SP.STRAIGHT,  SP.TURKED,  SP.UBDEFINED , 
SP.ERROR  5  -1>: 


enum  SwitchPosit 
Get SwitchPosit ion (block.id) 
int  block. id; 

The  setting  of  the  indicated  switch  block  is  returned  If  block.id  is  not  the 
ID  of  a  switch  block  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simulation. 
SP.ERROR  is  returned. 

3.4.3  Train  Status 

enum  TrainStatus  {TS.CRASHED,  TS.RUBNING,  TS.ERROR  =  -l}; 

enum  TrainStatus 
Get TrainStatus (train.id) 
int  train.id; 

If  the  indicated  train  has  state  operational.  TS.RURNING  is  returned.  If  that 
train's  state  is  derailed  or  collided.  TS.CRASHED  is  returned.  If  train.id  is  not 
the  ID  of  a  train  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simulation, 
TS.ERROR  is  returned. 
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3.4.4  Train  Motion 


enum  TrainMotion  {TH.STQPPED,  TM.HOVING,  TM_ERRDR  =  -1}; 

enoja  TrainMotion 
GetTrainMotion(train_id) 
int  train, id; 

If  the  indicated  train  has  .state  operational  and  at  least  one  of  the  train  s 
speed  t'train_id  acceleration  (itrain_id  non-zero.  TM_MQVING  is  returned. 
Otherwise,  TM_STQPPED  is  returned,  except  that  TM_ERROR  is  returned  if  train_id 
is  not  the  ID  of  a  train  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simula¬ 
tion. 


3.5  Voting 

The  vohng  service  supports  the  writing  of  fault-tolerant  control  programs  for  a 
Trainset  railroad.  By  default,  there  is  a  one-to-one  relationship  between  (!!Pl 
client  commands  (satisfying  various  preconditions,  as  described  in  Section  3.3) 
and  layout  actions.  The  voting  service  makes  it  possible  to  require  that  a  simu¬ 
lation  receive  a  specified  number  of  commands  from  different  CPI  clients 

within  a  certain  time  period  ^  voting  before  a  layout  ac'ion  can  occur. 

The  behavior  of  the  voting  service  is  governed  by  the  following  parameters. 

•  A  voting  quorum  Qvotiag  (integer).  When  the  voting  service  is  being 
employed,  a  layout  action  can  be  generated  only  if  Qvotmg  commands 
satisfying  the  conditions  below  are  received  from  different  CPI  clients. 

•  A  voting  window  ^voting  (floating  point,  seconds).  This  is  a  time  '  mit  af¬ 
ter  which  CPI  client  commands  expire.  If  a  command  has  not  contributed 
to  a  layout  action  within  •'Kvoimg  seconds  after  receipt  by  a  simulation, 
then  that  command  will  have  no  effect. 

•  A  sequence  number  seq  (integer)  that  is  a.s.sociated  with  each  CPI  com¬ 
mand. 

We  expect  Qvoiing  >  0-  ^votmg  >  0  and  seq  >  0. 

The  voting  service  is  enabled  only  for  commands  with  positive  sequence 
numbers.  Figuratively  speaking,  commands  with  different  positive  sequence 
numbers  participate  in  different  “elections.’’ 

The  follow'ing  paragraphs  provide  a  specification  of  the  voting  service. 

Sequence  number  0.  If  a  command  has  se<iuence  number  0.  then  that  com¬ 
mand  alone  generates  a  layout  action  immediately,  as  described  in  Section  3.3. 
The  values  of  and  Qy^d^g  have  no  effect  on  such  commands. 
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Accel 

3 

61 

1) 
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Accel 

1 

60 

E 

7:22:25 

SetSpeed 

2 

61 

V 

7:22:3(1 

SetSpeed 

3 

61 

Figure  Voting  example  ((lositive  seinieiice  iimiibers) 


Positives  soqu<m(:o  uuinbers.  H' a  .simulation  receives  Qvoon^f  mor''  com¬ 
mands  with  the  same  positive  sequence  nmnher  s(q  from  differenl  Cl’l  clients 
during  any  time  period  of  IVvotin;;  •'’*^<'<>nds  or  less,  then  a  single  layout  action  is 
generated.  Hy  default,  the  layout  action  generated  is  the  action  caused  (subject 
to  the  preconditiotis  listed  in  Section  H.3)  by  the  last  of  those  commands. 

No  commands  with  positive  .sequence  numbers  can  otherwise  contribute  to 
layout  actions.  Cominands  with  the  .same  seqitence  number  need  not  have  the 
same  arguments  nor  even  the  same  command  type.  A  command  can  contribiite 
to  the  generation  of  at  most  one  layout  action. 

For  example,  stippose  that  =  10  sec.  Quoting  —  that  the 

commands  in  Figure  3.2  are  received  b)'  a  simulation.  Then  only  one  layout 
action  w  ill  be  performed  by  that  simulation  as  of  the  time  7:22;30.  'That  layout 
action  will  be  fi.  occurring  at  time  7:22;2.o.  The  quorum  of  commands  consists 
of  (’  and  f:. 

The  values  of  voting  determined  when  a  Trainset  railroad 

simulation  is  invoked,  and  cannot  be  changed  during  a  simidaiion.  'I'he  default 
value  for  Qvaimg  i^  ^nd  the  default  value  for  ^^yotiug  ^  seconds. 

Sequence  numbers  can  be  modiru;J  dynamically  by  a  control  program.  The 
AC.'I  provides  an  internal  sequence-number  variable  ■•>fq.\cj  vvhose  value  is  auto¬ 
matically  sent  with  each  command.  The  value  of  the  variable  remains 

con.stant  unless  explicitly  modified,  and  the  inuial  value  is  0. 

In  order  to  employ  the  voting  service,  it  is  iiece.ssary  to  start  a  simulation 
with  Qvoiiiig  ^  ^  send  commands  that  have  positive  sequence  numbers. 

The  Af '1  provides  two  functions  for  modifying  the  value  of  a  .sequence  number. 


3.5.1  New  Sequence  Number 


int 

RewSeqNuraberO 

I'he  sequence  number  is  incremented  and  the  new  value  is  returned 

3.5.2  Set  Sequence  Number 

int 

SetSeqNumber (neH_val) 
int  new.val; 

If  new.val  is  non-negative,  the  sequence  number  !,(q  i.s  a-ssigned  nen.val. 
and  that  value  is  returned.  Otherwise,  fifq  is  left  unchanged  and  -1  is  returned 


3,6  rimer  Facilities 

'I'he  .A.CI  layer  provides  procedures  that  implement  a  .sitnple  timer  service  in 
which  time  quantities  are  represented  as  seconds  in  floating  point.  I'liese  rou¬ 
tines  affect  a  program  that  calls  them;  they  do  not  themselves  interact  with 
a  Trainset  railroad.  Alternative  time-inanagetnent  routities  or  direct  system 
calls  may  be  used  .i.stead  of  these  timer  procedures  when  writing  programs  that 
use  the  ACI.  Thus,  use  of  the  ACI  timer  facilities  is  optional. 

'I'he  five  timer  procedures  are  InitTimer.  GetTimer,  AwaitTiraer.  Cancel- 
Timer  and  Sleep. 

3.6.1  Initialize  Timer 

enum  Timer Retvirii  {THR_SUCCESS,  TMR_ERR0R  =  -1}; 
typedef  double  Seconds; 

enum  TimerReturn 
InitTimer (first ,  period,  f) 

Seconds  first;  /*  delay  to  first  timeout  */ 

Seconds  period;  /*  wait  between  successive  timeouts  */ 
void  (*f)();  /*  function  eiecuted  upon  each  timeout  */ 

InitTimer  initializes  the  timer  mechanism  to  execute  the  function  f  ()  after 
first  seconds  and  every  period  seconds  thereafter.  If  first  is  zero,  tlie  timer 
is  immediately  disabled.  If  period  is  zero,  tlie  timer  executes  f  ()  at  most  once 
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If  tlie  value  zero  is  specified  instead  of  a  function  i.  then  nothing  is  done  on 
timeouts  except  to  reset  the  tinier  as  appropriate.  TMR_SUCCESS  is  returned 
if  the  operation  succeeds.  If  a  time  argument  is  negative  or  a  low-level  error 
occurs.  TMR_ERR0R  is  returned. 

A  call  to  InitTimer  overrides  any  prior  timer  setting,  fhus.  there  is  no 
provision  for  more  than  one  timer  being  in  effect  at  any  time.  'I'he  timers  used 
in  other  ACI  functions,  including  GetDosnload.  the  ACl  queries  and  Sleep,  do 
not  interfere  with  InitTimer. 

3.6.2  Get  Timer  Values 

enum  TimerStatus  {TMS .DISABLED,  TMS.ONCE,  TMS.IHDEFIRITE, 
TMS.ERROR  =  -1}; 
typedef  double  Seconds ; 

erum  TimerStatus 
GetTimer(nextp,  periodp) 

Seconds  *nextp;  /*  next  scheduled  timeout  •/ 

Seconds  ♦periodp;  /♦  delay  between  successive  timeouts  */ 

GetTimer  stores  the  .seconds  remaining  until  the  next  titiier  expiration  in 
♦nextp  and  stores  the  current  period  between  timer  expirations  in  •periodp. 
The  return  value  is  TMS.DISABLED  if  the  timer  is  currently  disabled.  THS.OHCE 
if  the,  timer  is  scheduled  to  expire  once  only.  THS.IBDEFINITE  if  the  tinier  is 
scheduled  to  continue  indefinitely  and  TMS.ERROR  if  a  low-level  error  occurs 

3.6.3  Await  for  Timer 

void 

AwaitTimerO 

AwaitTimer  suspends  the  calling  process  until  an  ACI  timer  expiration  or 
another  operating  system  signal  occurs. 

3.6.4  Cancel  Timer 

enum  TimerReturn  fTHR.SUCCESS ,  TMR.ERROR  =  -l}; 

enum  TimerReturn 
CancelTimerO 
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CancelTimer  cancels  an  AC!  tinier,  TMR_SUCCESS  is  returned  if  the  oper¬ 
ation  succeeds.  CauicelTimer  fails  if  a  low-level  error  occurs,  in  which  case 
TMR_ERR0R  is  returned, 

3.6.5  Sleep 

enum  TimerReturn  {TMR.SUCCESS,  TMR.ERROR  =  -1}; 
typedel  double  Seconds; 

enum  TimerReturn 
Sleep(sec) 

Seconds  sec;  /*  max  number  oi  seconds  to  suspend  ♦/ 

Sleep  suspends  the  calling  process  for  indicated  number  of  seconds.  The 
value  TMR_SUCCESS  is  returned  if  the  suspension  was  not  interrupted  before  the 
time  limit  expired.  Otherwise,  TMR_ERR0R  is  returned. 

Sleep  does  not  interfere  with  the  operation  of  InitTimer.  Thus,  these 
functions  may  be  used  together,  e.g..  to  set  up  a  polling  loop  with  a  timeout. 
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Chapter  4 

Low-Level  Interface  (LLI) 


4.1  Introduction 

The  Low-Iy.’vel  Interface  (hl^l)  consists  of  predefined  tnessage  formats  and  re¬ 
lated  facilities  for  conmninicatiiiR  with  a  Trainset  railroad  siimilation.  This 
layer  is  used  to  iriiplenient  the  A(,’l  layer  in  the  Control  Program  Interface  (see 
figure  3.1). 

'I'his  chapter  gives  a  sketch  of  the  LM  layer.  A  reading  knowledge  of  the 
('  programming  language  is  assumed.  The  rest  of  this  chapter  includes  tlie 
following  .sections. 

•  Section  4.2  is  external  documentation  for  the  source  file  cpi.h  (see  Ap¬ 
pendix  C.  1 ).  The  internal  structure  of  that  file  is  descril>ed.  and  the  source 
lines  that  pertain  to  the  acceleration  command  are  discu.ssed  as  exanij)le.s, 

•  Section  4.3  describes  the  steps  necessary  for  a  client  to  connect  and  identify 
Itself  to  a  Trainset  railroad  siniulation. 

•  Sections  4.4  and  4.5  briefly  list  the  message  formats  that  are  used  for 
initial-stale  downloads,  commands  and  (pieries.  A  knowledge  of  the  ACI 
layer  (('hajiter  3)  is  as.siimed. 

For  a  programming  example  that  uses  the  I,1J  programming  layer,  see  the 
implementation  of  the  A(,’I  layer  in  the  .source  file  aci.c  (Appendix  (’  2). 


4.2  Messages 

In  the  I, hi  layer,  a  control  program  interacts  witfi  a  Trainset  railroad  smiuia 
tion  by  sending  and  receiving  messages.  An  LLI  nitfisaijf  is  an  ASCII  cfiaracter 
string  that  is  organized  according  to  one  of  the  rrussagf  foriiials  defined  in 


m 

#define  MSG_CPI_ACCEL  "Xa‘/,d,*/.d:*/.d:*/.lf#" 
typedef  struct  -C 

Bint  client_id;  /*  unique  identifier  for  this  client  */ 
int  seq.num;  /♦  label  for  this  comnand  */ 
int  train_id;  /♦  simulator  train  number  •/ 
double  duration;  /♦  time  to  accelerate  in  seconds  ♦/ 

)•  MsgCPIAccel; 

#define  MSG_CPI_ACCEL_ARGC  4 

#define  MsgCPIAccelArgs(buff ,  datap)  (buff,  MSG_CPI_ACCEL,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->duration  ) 

a 

#define  CreateMsgCPIAcceKbulf ,  datap)  sprintf  MsgCPIAccelArgs(buff ,  (datap)) 
[T|  #define  ParseMsgCPIAccel(buff ,  datap)  sscanf  MsgCPIAccelArgs(buff ,  ft(datap)) 


Figure  4.1:  Excerpt  from  cpi.h  relating  to  acceleration  coniniand. 


cpi.h.  Each  such  message  format  consists  of  /ieWs  for  representing  data,  to¬ 
gether  with  an  identifying  header  and  delimiter  characters. 

For  example,  consider  Figure  4.1.  an  excerpt  from  cpi.h.  Line  [T]  defines  a 
message  format  called  MSQ.CPI.ACCEL.  That  message  format  has  the  following 
syntax. 

Xa  (integer)  ,  (integer)  :  (integer)  :  (Boat)  It 

There  are  four  fields.  The  notations  (integer)  and  (Boat)  indicate  ASCII  repre¬ 
sentations  of  integer  and  floating  point  numbers.  The  total  length  of  a  message 
depends  on  the  lengths  of  the  data  in  its  fields. 

In  general,  for  each  message  format  in  cpi.h  there  is  a  type  definition  of 
an  associated  data  structure  whose  components  correspond  to  the  fields  of  that 
message  formal,  in  the  same  order.*  For  MSG_CPI_ACCEL,  the  associated  data 
structure  is  called  MsgCPIAccel.  See  the  lines  near  [7]  in  Figure  4.1. 

A  comparison  of  the  message  format  MSG_CP1_ACCEL  and  the  documented 
data  structure  MsgCPIAccel  shows  that  the  first  (integer)  field  in  that  message 
format  holds  the  client  ID,-  the  second  (u.teger)  field  holds  the  voting  sequence 
number  of  an  Accelerate  command,  etc. 

For  each  message  format,  a  macro  has  been  defined  that  produces  a  string 
in  that  message  format,  using  values  stored  in  a  variable  of  the  associated  data 

'Four  CPI  message  formats  are  ^lssociated  with  basic  data  types  that  are  not  explic¬ 
itly  defined  as  structures  in  cpi.h.  These  are  HSO-CPUIIT  (string).  HSGJtCK  (string). 
nSGXPI-DOWILDJlDIE  (integer)  and  HSGJlUITJtLL  (string). 

unique  client  ID  is  assigned  to  each  Cf’I  client  when  that  client  connects  to  a  simulation, 
ais  described  below. 
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type  for  the  fields.  Another  macro  has  been  defined  for  parsing  such  a  mes¬ 
sage  into  a  variable  the  associated  data  type.  These  macros  are  provided  as 
a  convenience.  In  the  case  of  MSG_CPI_ACCEL.  the  creation  macro  is  called 
CreateMsgCPIAccel  and  is  defined  by  line  in  Figure  4.1.  The  message¬ 
parsing  macro  is  PaxseMsgCPIAccel  defined  on  line  [Tj. 

In  general,  for  any  such  macro  associated  with  a  message  format: 

•  There  are  two  arguments,  a  character  string  buffer  holding  the  message 
and  a  pointer  to  a  variable  of  the  associated  data  structure  type  holding 
the  values. 

•  The  run-time  replacement  value  of  such  a  macro  is  the  length  of  the  re¬ 
sulting  message,  not  counting  a  null  byte  that  is  placed  at  the  end  of  that 
message  string.^ 

Thus,  the  macro  CreateMsgCPIAccel  behaves  like  a  function  with  the  following 
heading. 


int 

CreateMsgCPIAccel (buff ,  datap) 

char  buffQ;  /•  resulting  message  is  placed  here  •/ 
MsgCPIAccel  ♦datap;  /♦  points  to  data  values  ♦/ 


4.3  Initiating  Communication 

Establishing  communication  betw'een  a  client  and  a  Trainset  railroad  simula¬ 
tion  requires  two  steps. 

1.  Connection.  Create  a  netw'ork  connection  between  that  client  and  that 
simulation.  A  simulation  provides  well-known  ports  for  supported  commu¬ 
nication  protocol  families  (e.g.,  TCP/IP,  DElCnet)  and  is  capable  of  socket 
or  stream  transmissions  in  each  case.  The  function  GetSimPort  defined  in 
the  source  file  lib/syslocal .  c  returns  the  well-known  port,  given  a  base 
port  (provided  in  lib/syslocal  .h),  a  host  name  and  an  integer  simnum 
that  distinguishes  between  multiple  simulations  running  on  the  same  host. 
Use  standard  techniques  to  open  one  bidirectional  communication  line. 

2.  Registration.  Send  a  registration  message  to  that  simulation  to  declare 
a  client  type  (CPI  or  monitor)  and  receive  a  client  ID.  A  registration 
message  for  a  CPI  client  has  the  message  format  MSG_CPI_IHIT 

CPI  (one  space)  (string)  '/. 

■’Sending  a  terminating  null  byte  to  a  stimulation  as  part  of  a  message  is  optional 


.=>2 


where  (string)  is  any  sequence  of  ciiaraclers  that  are  not  llie  percent  sign 
V,  and  is  convenlionally  the  file  name  of  tliat  client 's  executable.  'I'he  smi 
ulation  replies  with  an  acknowledgement  message  in  the  format  MSG_ACK. 
as  follows. 

ack  (one  spare)  (integer)  #  % 

The  {integer}  field  in  that  message  represents  the  unique  client  li)  number 
to  be  used  in  all  commands  and  queries  from  that  client  to  the  simulation. 

The  macros  CreateMsgCPIInit  and  ParseMsgAck  may  be  used  if  desired, 

VVe  assume  that  each  client  creates  only  one  connection  with  a  simulatioti. 
For  the  remainder  of  this  chapter,  message  formats  will  be  cited  by  name 
only,  omitting  mention  of  syntax,  related  macros,  etc.  See  Appendix  C.l  for 
syntax  details. 


4.4  Initial-State  Download 

After  initiating  communication  with  a  simulation,  a  (.’PI  client  can  receive  a 
report  of  the  current  global  state  of  the  railroad  being  simulated.  Such  a  report 
is  called  a  download. 

To  request  a  download,  a  control  program  must  send  a  message  to  a  simu¬ 
lation  using  the  message  format  MSG_CPX_DOWHLD_REQUEST.  'I'he  acknowledge¬ 
ment  from  the  simulation  is  the  download  itself.  'Fhe  download  consists  of 
messages  in  the  following  DQWNLD  formats. 

•  J1SG_CPI_D0WIILD_ GENERAL  transmits  constants  that  describe  a  railroad  in 
general,  e.g.,  the  number  of  blocks. 

•  MSG_CPI_DOWRLD_TRAIN  describes  attributes  of  trains.  One  message  in 
this  format  is  sent  per  train. 

•  MSG_CPI_DOWHLD_BLOCK  describes  a  block,  MSG_CPI_DOWNLD_LINK  gives 
block  attachments  for  a  block  as  described  in  Section  3.2.  One  message  in 
each  of  these  formats  is  sent  per  block. 

•  HSG_CPI_DOWNLD_DONE  marks  the  end  of  a  download. 

Only  one  download  request  is  honored  by  a  simulation  per  client  connection. 


4.5  Commands  and  Queries 

•  MSG_CPI_SET_SWITCH, MSG_CPI_ACCEL,  HSG_CPI_DECEL, 

MSG_CPI_SET_SPEED,  MSG_CPI_SET_DIR.  MSG_CPI_EMER_STO’=  and 
HSG_CPI_STA_STOP  request  the  commands  described  in  Section  3.3.  No 
acknowledgement  message  is  sent  in  response  to  such  a  command. 
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•  MSG_CPI_BLOCK_OCC  requests  a  block's  occiipHiicy  staius,  A  simulation 
responds  with  a  message'  "o”  if  that  block  is  occupied  or  "f"  (for  "free") 
if  it  is  not  occupied. 

•  MSG_CPI_SWITCH_POSIT  asks  for  the  current  setting  of  a  switch  block  The 
response  is  "s"  for  straight,  "t"  for  turned,  or  "u"  for  undefined. 

•  MSG_CPI_TRAIN_STATUS  inquires  about  a  train's  status.  A  simulation  re¬ 
sponds  with  "r"  for  running  (operational  state)  or  "c"  for  crashed  (col¬ 
lided  or  derailed  stales). 

•  HSG_CPI_TRAIR_MOTION  queries  whether  a  train  is  moving.  The  response 
is  "s*'  for  stopjied  or  "m"  for  moving  A  train  is  moving  if  it  is  operational 
and  at  least  one  of  its  speed  and  acceleration  is  non-zero.  A  train  is 
stopped  if  it  is  not  moving. 


4,6  Quit  Message  From  the  Simulator 

Just  before  a  Trainset  simulation  exits  normally,  it  sends  a  me.ssage  in 
the  format  MSG_QUIT_ALL  to  ail  of  its  clients.  Receipt  of  this  me.ssage  is  a 
certain  indicator  that  a  simulation  has  finished. 


'Note.  (Jne-character  return  strings  such  as  “o"  are  sent  as  two-b.vle  messages  from  the 
simulator,  including  the  temunating  null  byte. 
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Appendix  A 

Constants  Used  by  Trainset 


Constant 

name 

Description 

Typical 

value 

Page 

references' 

ACC 

Standard  acceleration  rate  for  trains 

1.5  rn  /sec ‘ 

36.  40.  41.  42 

Aemer 

Emergency-stop  acceleration  rate  for  trains 

2.5  m/sec^ 

36.  37,  40.  43 

if  Across 

Length  of  a  cross  block 

55  rn 

33 

L  E  A  joj'n 

Length  of  a  join  block 

55  in 

32 

switch 

Length  of  a  switch  block 

55  m 

34 

Length  of  block  B 

35  to  300  m 

30 

ir 

Length  of  train  r 

150  to  500  m 

35 

MS, 

Minimum  speed  limit  on  block  B 

0  m/sec 

30.  36.  40 

MX, 

Maximum  speed  limit  on  block  B 

60  in/sec 

30.  36.  40 

A  blocks 

Number  of  blocks  in  a  layout 

5  to  50 

40 

A  trains 

Number  of  trains  in  a  layout 

1  to  3 

40 

Q  iotiag 

Voting  quorum 

2 

40.  45.  46 

^switch 

Time  for  a  switch  block  to  change  settings 

2  sec 

33.  40.  41 

vss. 

Station  stop  speed  for  a  station  block 

30  m/sec 

34,  37.  40.  43 

voting 

Voting  window 

5  sec 

40.  45.  46 

^  A  boldfact^  number  indicates  the  primary  reference  for  a  symbol. 
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Appendix  B 

Code  Listings:  ACI 


B.l  aci.h,  Interface  Header  File 

/*  aci.h  —  header  file  for  ACI. 

This  file  defines  types  and  constants  and  declares  functions 
found  in  the  ACI  library  libaci.a  . 

Created  by  R.  Brown,  4/91  •/ 

/*  all  units  are  laks  unless  otherwise  indicated  */ 


/* 

*  constant  definitions 

•/ 


#ifndef  MAX.TRAINS 

#define  MAX_TRAINS  10  /*  marimum  number  of  trains  in  a  layout  •/ 

#endif 

#ifndef  MAX.BLOCKS 

#define  MAX.BLOCKS  100  /*  maximum  number  of  blocks  in  a  layout  ♦/ 

#endif 


/* 

*  type  definitions  for  storing  a  state  download 

*/ 
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/*  BlockType  specifies  the  type  of  a  block  */ 

envun  BlockType  -[BT.REGULAR ,  BT.STATIDR,  BT_SWITCH,  BT.JOIN,  aT.CRQSS}; 


/•  BlockTypeData  represents  data  that  is  specific  to  a  type  of  block  */ 

union  BlockTypeData  •( 

struct  •{  BT.REGULAR  blocks  */ 
int  tail,  head;  /*  terminators  ♦/ 

>  rg; 

struct  {  /*  BT.STATION  blocks  */ 

int  tail,  head;  /♦  terminators  */ 
double  sta.stop.speed;  /♦  station  stop  speed  ♦/ 

}■  St; 

struct  {  /*  BT.SWITCH  blocks  */ 

int  tail,  straight,  turn;  /*  terminators  •/ 

>  sw; 

struct  {  /♦  BT.JOIH  blocks  •/ 

int  tail,  headl,  head2;  /•  terminators  •/ 

>  jn; 

struct  {  /*  BT.CROSS  (sub)blocks 

int  tail,  head;  /•  terminators  ♦/ 

int  cross.id;  /*  block  ID  of  this  subblock’s  cross  block  ♦/ 

>  cr; 

>: 

/*  BlockData  represents  the  download  information  for  a  specific  block  */ 

typedef  struct  BlockData  { 

int  block.id;  /*  identifies  the  block  */ 
enum  BlockType  type; 
double  length; 

double  max.speed,  rain.speed;  /♦  trains  derail  that  violate  these  limits  ♦/ 
union  BlockTypeData  t;  /•  additional  data  that  depends  on  block  type  */ 

>  BlockData; 
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/*  Location  specifies  a  position  oithin  a  block  */ 
struct  Location  {. 

int  block;  /*  id  of  a  block  containing  the  location  */ 
double  offset:  /*  distance  from  tail  of  that  block  to  the  location  */ 
)■  Location; 


/*  TrainData  represents  the  download  information  for  a  specific  train  */ 

typedef  struct  TrainData  { 

int  train.id;  /*  identifies  the  train  */ 
double  length; 

struct  Location  head,  tail;  /*  init  positions  of  train’s  ends  */ 

}  TrainData; 


/*  LayoutData  represents  all  information  received  in  a  download  */ 

typedef  struct  LayoutData  •[ 

int  block_ct;  /*  number  of  blocks  */ 
int  train.ct;  /•  number  of  trains  */ 

double  acc,  emcr.acc;  /♦  standard  and  emergency  stop  acceleration  rates*/ 
double  switch.time;  /•  time  required  for  switch  block  to  change  posit  */ 
int  voting.quorura;  /•  number  of  agreeing  commands  required  for  an  action  •/ 
double  voting_window;  /*  time  limit  after  which  commands  expire  */ 

BlockData  blocks CHAX_BL0CKS3 ;  /*  block-specific  data  */ 

TrainData  trains [MAX_TRAINS3 ;  /*  train-specific  data  */ 

}  LayoutData; 


/♦ 

♦  ACI  function  declarations,  with  associated  type  definitions 

*/ 


/*  GetDownload,  for  connecting  to  a  simulated  railroad  and  receiving 
a  report  of  that  railroad’s  state.  */ 

LayoutData  *GetDownload() ; 
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/*  ACI  commands  */ 


enum  HesPosit  {NP.STRAIGHT,  HP_TUESED}; 
void  SetSsitchO : 

void  AccelerateO ; 

void  DecelerateO ; 

void  SetSpeedO ; 

void  SetDirectionO ; 

void  EmergencyStopO ; 

ennm  StationStopMode  -tSS .DISABLED,  SS_EKABLED>: 
void  StationStopO ; 


/*  ACI  queries  */ 

enum  Occupancy  <0C_FREE,  OC.OCCUPIED,  OC.ERROR  =  -1>; 
enum  Occupancy  GetBlockOccupancyO; 

enum  SwitchPosit  {SP.STRAIGHT,  SP.TURNED,  SP.UHDEFINED,  SP.ERRDR  =  -1} 
enum  SwitchPosit  GetSwitchPositionO ; 

enum  TrainStatus  {TS.CRASHED,  TS.RUBNING,  TS.ERROR  =  -1}; 
enum  TrainStatus  GetTrainStatusO ; 

enum  TrainMotion  {TM.STOPPED,  TM .MOVING,  TM.ERROR  =  -1}; 
enum  TrainMotion  GetTraiuMotionO ; 


/*  changes  to  voting  service  sequence  number  ♦/ 
int  SetSeqNiunberO ; 
int  NewSeqNumberO ; 


/♦  timer  facility  */ 
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typedef  double  Seconds; 

enum  TimerReturn  {THR.SUCCESS ,  TMR.ERROR  =  -1}; 
enum  TimerReturn  InitTimerO; 

enum  TimerStatus  {THS.DISABLED,  TMS_DNCE,  THS.INDEFIHITE,  TMS_ERRQR  =  -1>; 
enum  TimerStatus  GetTimerO; 

void  AsaitTimer 0 ; 

enum  TimerReturn  CancelTimerO ; 

enum  TimerReturn  SleepO; 


B.2  acitest.c,  Example  Using  the  ACI  Inter¬ 
face 

/*  $RCSfile:  acitest.c, v  $  $Revision:  1.8  $  $Date:  92/07/17  10:58:43  $  */ 

/*  acitest.c  —  manual  demonstration  of  the  ACI  interface.  ♦/ 

#include  <stdio.h> 

#include  "aci.h" 

#define  TIKEOUT  60.0  /♦  seconds  to  contact  the  simulator  ♦/ 

#define  MAXLINE  100  /*  maximum  input  length  */ 

#define  NORMAL  0  /*  exit  code  for  normal  exit  ♦/ 

#define  ERROR  1  /♦  exit  code  for  error  exit  */ 

#define  USAGE  "Usage:  '/s  [-d]  Csimhost  [simnum]]\n"  /*  diagnostic  msg  */ 
#define  QUIT_C0MMAND  "q"  /♦  user  entry  for  quit  command  */ 

enum  command_type  { 

/*  commands  */ 

SET.SWITCH  =  1,  ACCELERATE.  DECELERATE,  SET.SPEED, 

SET .DIRECTION,  EMERGENCY .STOP ,  STATION.STOP , 

/*  queries  */ 

GET.BLOCK.OCCUPANCY,  GET.SWITCH.POSITION,  GET.TRAIN.STATUS,  GET.TRAIN.MOTION, 
/*  other  */ 

SET.SEQ.NUMBER,  NEW.SEQ.NUMBER, 

QUIT,  HELP 

>: 

struct  command  {. 


60 


enum  command 
char  •code ; 
char  *name; 
char  ‘args ; 


type  type;  /*  type  of  this  command  or  query  •/ 

/♦  entry  code  lor  this  command  or  query  */ 

/♦  lull  name  ol  this  ACl  command  or  query  */ 

/*  names  ol  arguments  required  lor  this  command  or  query  • 


/ 


}; 


/*  HULL-terminated  table  ol  command  types,  codes  and  niuues  »/ 

struct  command  command.table  []  =  { 

/•  commands  •/ 

SET_SWITCH,  "SB",  "SetSBitch",  "<block_id>  <nfcB_posit>" , 

ACCELERATE,  "ac",  "Accelerate",  "<train_id>  <duration>", 

DECELERATE,  "dc",  "Decelerate",  "<train_id>  <duration>", 

SET.SPEED,  "sp",  "SetSpeed",  "<train_id>  <goal_speed>" , 
SET.DIRECTIQN,  "sd",  "SetDirection" ,  "<train_id>  <neB_dir>" , 
EHERGENCY_STOP ,  "es",  "EmergencyStop" ,  "<train_:d>" , 
STATIGH_STQP ,  "st",  “StationStop" ,  "<train_id>  <neB_val>" , 

/♦  queries  •/ 

GET_BLOCK_OCCUPANCY ,  "o",  "GetBlockOccupancy” ,  "<block_id>"  , 
GET_SWITCH_POSITIOH ,  "p",  "GetSBitchPosition" .  "<block.id>" , 
GET_TRAIN_STATUS ,  "s",  "GetTrainStatus" ,  "<train_id>" , 
GET_TRAIH_MQTIOB ,  "m",  "GetTrainMotion" ,  "<traia.id>" , 

/♦  other  */ 

SET_SEQ_1IUMBER,  "sn",  "SetSeqHumber" ,  "<neB_val>", 
NEW_SEQ_NUMBER,  "nn" ,  "SeBSeqNumber" ,  "", 

QUIT,  QUIT.COHMAND,  "Quit", 

HELP,  "7",  "Help".  "  h  help", 

(enura  command. type)  0,  (chaur  ♦)  0,  (char  •)  0,  (char  •)  0 

}; 


/**««^*****»4,««*«  ««**««******•*•  *•#**#**«*  4i«**«***4,***i4i  **«•*•«***/ 

/*  Whitespace  takes  a  char  argument  c.  Evaluates  to  non-zero  il 
c  is  whitespace,  zero  otherwise  */ 

Adeline  Whitespace (c)  (c  ==  ’  ’  1 1  c  ==  '\t’  I  I  c  ==  ’\n') 


/t  *********************************************  t*t»Ht*»*******»*tt/ 

/*  CommandLookup  determines  the  command  corresponding  to  a  code 
entered  to  identify  a  command. 

Any  whitespace  characters  at  the  beginning  ol  entry  are  ignored. 
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Returns  the  index  in  the  table  of  the  indicated  command,  or 

-1  if  the  code  was  empty  or  the  given  entry  code  was  not  found.  ♦/ 

int 

C  omraandLookup ( entry ) 

char  *entry;  /*  entry  code  to  be  interpreted  as  a  command  */ 

i 

struct  command  *p;  /*  pointer  into  commzuid  table  */ 

while  (*entry  6ft  Whitespace(*entry)) 
entry++ ; 
if  ('♦entry) 
return  (-1); 

/♦  entry  is  non-empty  string  beginning  with  a  non-whitespace  char  */ 

if  (♦entry  ==  ’h’) 
entry  = 

/♦  if  request  is  for  Help  then  entry  has  value  "?"  ♦/ 

for  (p  =  command. table;  p->type:  p++)  { 
if  (! strcmp( entry ,  p->code))  { 
return  (p  -  command .table) ; 

} 

} 

/*  entry  does  not  match  a  code  in  the  table  ♦/ 

printfC  no  match  found\n*’); 
return  (-1); 


/*  PrintDownload  displays  every  field  received  in  a  download  ♦/ 
void 

PrintDownload(dp,  simhost,  simnum) 

LayoutData  ♦dp;  /♦  data  received  from  download  */ 

char  ♦simhost;  /♦  name  of  the  host  system  running  the  simulator  */ 

int  simnum;  /♦  identifier  for  a  running  simulation  on  that  host  ♦/ 

{ 

int  i;  /♦  loop  control  ♦/ 

TrainData  ♦tp;  /♦  utility  pointer  to  data  for  a  specific  train  ♦/ 
BlockData  ♦bp;  /*  utility  pointer  to  data  for  a  specific  block  ♦/ 
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printf ("Contents  oi  download  from  simhost  */,s,  simnum  */id:\n", 
simhost,  simnum); 

printf ("\nGeneral  parameters : \n") ; 
printf  ("  There  are  */.d  blocks  and  %d  trains\n", 
dp->block_ct ,  dp->train_ct ) ; 

printf  ("  Train  acceleration  rates  (m/sec):  standard  Xf ,  emergency  stop  */,f\n‘', 
dp->acc,  dp->emer_acc) ; 

printf  ("  Switches  take  ‘/if  seconds  to  change  positionNn", 
dp->SHitch_time) ; 

printf ("  The  voting  quoriun  is  '/d  and  the  voting  window  is  Xi  seconds\n", 
dp->voting_quorum,  dp->voting_window) ; 

printf ("\nBlocks : \n") ; 
for  (i=0;  i  <  dp->block_ct ;  i++)  { 

bp  =  ftdp->blocks [i] ; 

printf  ("  Block  */.d  has  typo  ",  bp->block_id) ; 
switch  (bp->type)  { 
case  BT_REGULAR; 
printf ("REGULAR"); 
break ; 

case  BT.STATIOH; 
printf ("STATION"); 
break; 

case  BT.SWITCH: 
printf ("SWITCH"); 
break; 

case  BT.JQIN: 
printf ("JOIN"); 
break; 

case  BT_CR0SS: 
printf ("CROSS"); 
break; 

> 

printf  ("  and  length  '/,f  meters\n",  bp->length): 

printf  ("  Its  speed  limits  are  Xi  (minimum)  and  '/,f  (maiimum)\n" , 
bp->min_speed,  bp->max_speed) ; 
printf ("  Its  terminators  are  connected  to  blocks  "); 
switch  (bp->type)  { 
case  BT_REGULAR: 

printf  ("'/,d  (head)  and  '/.d  (tail)\n", 
bp->t . rg , head ,  bp->t.rg.tail); 
break: 


case  BT_STATIQN; 

printf("yid  (head)  and  ‘/,d  {tail)\n", 
bp->t.st.head.  bp->t . st .tail) ; 

printK"  Its  station  stop  speed  is  '/,f  m/secXn", 
bp->t . st . sta_stop_speed) ; 
break; 

case  BT.SWITCH: 

printf(  ’‘,id  (straight  head),  */.d  (turn  head)  and  */id  (tail)\n", 
bp->t.SH. straight,  bp->t . sb . turn,  bp->t . sb . tail ) ; 
break; 

case  BT_J0IN: 

printf("*/,d  (headl),  '/A  (head2)  and  */id  (tail)\n", 
bp->t . jn.headi ,  bp->t. jn.head2,  bp->t . jn.tail) ; 
break; 

case  BT_CR0SS : 

printf("'/,d  (head)  and  */,d  (tail)\n'', 
bp->t.cr.head,  bp->t .cr .tail) ; 

printf("  This  is  a  subblock  of  the  cross  block  Bith  ID  */,d\n", 
bp->t . cr . cross.id) ; 
break; 

> 

> 

printl ("\nTrains :\n") ; 
for  (i=0;  i  <  dp->train_ct ;  i++)  { 

tp  =  &dp->traiasCi] ; 

printfC  Train  */,d  has  length  V.f  metersNn", 
tp->train_id,  tp->length); 

printf("  Its  head  end  is  in  block  ’/,d,  */,f  meters  from  tail  terminatorNn" 
tp->head. block,  tp->head.off set) ; 

printf("  Its  tail  end  is  in  block  ’/.d,  '/.f  meters  from  tail  terminator \n" 
tp->tail .block,  tp->tail . offset) ; 

} 

printf ("\nEnd  of  configuration  dosnload  report\n\n") ; 
return; 


/*  GetValue  attempts  to  locate  a  value  in  the  string  buff. 

If  buff  contains  only  Bhitespace,  prompt  is  printed  and  standard  input 
is  read  until  some  non-shit espace  characters  are  entered. 
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II  a  value  matching  the  printf  format  fmt  is  found  in  buff  or  stdin, 
then  its  value  is  placed  in  *valp  amd  a  pointer  is  returned  that  points 
to  the  first  whitespace  character  after  the  value. 

If  the  next  non-whitespace  characters  do  not  scan  according  to  fmt , 
an  error  message  requesting  user  to  try  again  is  printed  and 
NULL  is  returned.  */ 

char  * 

GetValue{buff ,  fmt.  valp,  prompt) 

char  •buff ;  /•  buffer  that  may  contain  a  value  */ 

char  •fmt;  /•  printf-style  format  for  reading  the  value  •/ 

char  •valp;  /♦  to  receive  value  if  one  is  found  */ 

chair  *prompt;  /•  prompt,  used  to  obtain  standaord  input  ♦/ 

char  •p;  /•  utility  pointer  •/ 

/♦  invaur:  buff  is  unexamined  •/ 
do  { 

for  (p  =  buff;  ♦p  bk  Whitespace(^p) ;  p++) 

> 

/•  •p  is  null-byte  or  first  non-whitespace  •/ 
if  (!*p)  { 

printf ("  '/,s:  ",  prompt); 

gets (buff ) ; 
p  =  buff; 

} 

/•  *p  is  first  non-whitespace  char,  or  p  points  to  beginning  of 
an  unexarained  (yet  possibly  empty)  buff  */ 

>  while  (l^p  II  Vfhitespace(*p) ) ; 

/•  •p  is  non-whitespace  */ 

if  (sscanf(p,  fmt,  valp)  !=  1)  { 
printf ("Error  reading  value  —  try  againXn"); 
return  (NULL); 

} 

/•  value  was  successfully  read  into  •valp  •/ 
while  (•p  bb  !Whitespace(^p) ) 

P++; 

return  (p) ; 

> 
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/*  Getint  and  GetFloat  are  macros  for  getting  values  of  certain  types 
from  buff n  or  standard  input,  via  GetValue  above  ♦/ 

#define  GetlntCbuff,  valp,  prompt)  GetValue  (buff ,  "*/,d" ,  valp,  prompt) 
#define  GetFloat  (buff ,  valp,  prompt)  GetValue  (buff ,  "'/.If",  valp,  prompt) 


****************************************************/ 

main(argc,  argv) 

int  argc;  /*  number  of  command  line  arguments  remaining  */ 
char  *argv[];  /*  list  of  command  line  arguments  remaining  */ 

{ 

char  ♦progname;  /*  name  of  this  program  ♦/ 

char  simhost [HAXLIHE+l] ;  /*  name  of  host  system  running  simulator  ♦/ 

int  simnum  =0;  /•  number  of  this  simulator  */ 

int  print_do»nload  =0;  /*  boolean;  set  non-zero  to  print  download  */ 

char  buff [MAXLIHE+l] ;  /•  buffer  for  interactive  input  */ 

LayoutData  *datap;  /*  data  received  from  download  */ 

int  index;  /*  index  of  a  command  table  entry  •/ 

char  ♦p,  ♦♦tablep:  /*  utility  pointers  */ 

struct  command  ♦commandp;  /*  pointer  into  command  table  ♦/ 

char  prompt CHAXLIHE] ;  /*  holds  any  prompts  for  user  input  */ 

p  =  progname  =  *argv++;  argc — ; 

/♦  invar:  there  are  no  slashes  in  the  string  progname  before  p  */ 
while  (*p) 

if  (*p++  ==  '/’) 
progname  =  p; 

/*  progname  is  null-terminated  program  name  after  stripping  directories  ♦/ 

if  (argc  >  0  ftft  ♦♦argv  -=  ’-’)  { 

/♦  a  flag  was  encountered  */ 
if  ( !  strcmp(^argv,  "-d"))  -C 
print_download++ ; 
argc—;  argv++; 

)■  else  { 

fprintf (stderr,  USAGE,  progname); 
exit  (ERROR): 

} 

> 

/♦  all  flags  have  been  processed  ♦/ 
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if  (argc  >  0)  { 

/♦  a  next  argument  exists,  presumed  to  be  simhost  ♦/ 
if  (strlen(*argv)  >  MAXLINE)  •( 

fprintf  (stderr ,  "simulator  host  name  too  long,  max  =  ‘/,d\n" ,  HAXLIHE) ; 
exit  (ERROR); 

> 

/*  first  arg  will  fit  in  simhost  */ 

strcpyCsimhost,  *argv++); 
argc—: 

}  else  { 

/*  no  more  command-line  arguments  remain  ♦/ 

printf ("Enter  name  of  host  running  simulator  [LOCAL  HOST];  "); 
if  ( !g6ts(simhost) )  { 

fprintf (stderr ,  "error  getting  host  name\n"); 
exit  (ERROR); 

> 

printf ("Enter  simulator  number  on  that  host  [0];  "); 
if  (!  gets  (buff))  ■( 

fprintf (stderr,  "error  getting  simulator  numberXn"); 
exit  (ERROR) ; 

} 

simnum  =  (*buff)  ?  atoi(buff)  :  0; 

} 

/*  simhost  contains  (possibly  empty)  null-terminated  string  AND 

if  no  argument  remains  then  simnum  holds  specified  or  default  value  */ 

if  (argc  >  0)  { 

/*  another  argument  second  parameter  exists,  presumed  to  be  simnum  */ 

sscanf  (fargY+t,  "'/,d",  isimnum) ; 

argc—; 

} 

/*  simnum  holds  specified  or  default  value  */ 


printf  ("Connecting  to  simulator  using  '/..If  second  timeout ..  An" ,  TIMEOUT); 
if  ( ! (datap  =  GetDo¥nload(simhost ,  simnum,  progname,  TIMEOUT)))  { 
fprintf (stderr ,  "GetDownload  failedXn"); 
exit  (ERROR); 

} 

/*  download  was  successfully  received  */ 
if  (print_download) 
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PrintDownloadCdatap,  simhost,  simnum) ; 

printf ("Enter  ?  lor  a  list  of  coaunandsVn") ; 

for  (; ; )  { 
do  { 

printl(‘"/,s>  progname);  /•  prompt  */ 

bunco]  =  ’\0’: 
if  (! gets (buff) ) 

/*  end  of  input  encountered  •/ 
sprintf (buff,  QUIT.COMMAED) ; 

for  (p=buff;  *p  ftft  Whitespace(*p) ;  p++) 

I 

/*  p  points  to  first  non-whitespace  char  of  buff,  or  null  byte  */ 

}  while  ( ! ♦p) ; 

/*  buffC]  contains  a  new  non-empty  null-terminated  command  */ 
while  (*p  IWhitespaceCfp) ) 

P++; 

/*  *p  is  null-byte  or  first  whitespace  after  command  code  */ 

If  (*p) 

•P++  =  ’\o’ : 

/*  buff  is  null-terminated  string  holding  a  non-empty  command  code 

consisting  of  non-whitespace  chars,  and  holding  QUIT.COHMAND  on  EOF, 
AHD  string  p  is  any  remainder  of  the  (null-terminated)  input  line  */ 

if  ((index  =  CommandLookup(buff ) )  ==  -1)  { 

print! ("Unrecognized  command  code  "/.s’  (enter  lor  help)\n", 
buff); 
continue; 

} 

/*  a  recognized  command  code  was  entered  */ 

/*  gather  arguments  lor  the  appropriate  ACI  routine  and  call  it  •/ 

switch  (coramand_table [index]  .type)  •( 
case  SET.SWITCH: 

int  block_id;  /*  identifier  of  the  switch  block  ♦/ 
enum  NewPosit  new.posit;  /*  desired  position  */ 

p  =  Getlnt(p,  &block_id,  "SetSwitch.  ID  of  switch  block"); 
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if  (!p)  continue; 


sprintf (prompt,  "Besr  position  C/.d  =  straight,  '/.d  =  turned)*', 
NP.STRAIGHT,  NP.TURNED); 
p  =  Getlnt(p,  ftnew_posit,  prompt); 
if  ('p)  continue; 

/♦  all  aa-guments  successfully  obtained  •/ 

SetSwitch(block_id,  nes.posit); 
break; 

} 

case  ACCELERATE; 
case  DECELERATE: 

{ 

int  train_id;  /•  identifier  of  the  train  */ 

double  duration:  /*  number  of  seconds  to  accelerate  */ 

sprintf  (prompt ,  /ts.  ID  of  train",  coinmand_table  [index]  .name) 
p  =  Getlnt(p,  fttrain.id,  prompt); 
if  (!p)  continue; 

sprintf  (prompt ,  "Seconds  to  V.s" ,  command.table  [index]  .name); 
p  -  GetFloat(p,  Aduration,  prompt); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 

if  (command.table [index] .type  ==  ACCELERATE) 
Accelerate(train_id,  duration); 

else 

Decelerate(train_id,  duration); 
break; 

> 

case  SET.SPEED: 

{ 

int  train.id;  /*  identifier  of  the  train  •/ 

double  goal.speed;  /*  speed  to  accelerate  or  decelerate  to  •/ 

p  =  Getlnt(p,  Atrain.id,  "SetSpeed.  ID  of  train"); 
if  (!p)  continue; 

p  =  GetFloat(p,  Agoal.speed,  "Hes  goal  speed"); 
if  (!p)  continue: 
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/*  all  argiunents  successfully  obtained  ♦/ 

SetSpeed(train_id,  goal_speed); 
break; 

> 

case  SET.DIRECTIQS ; 

■[ 

int  train_id;  /*  identifier  of  the  train  »/ 
int  new_dir;  /*  indicator  of  new  direction  ♦/ 

p  =  GetIntCp,  &train_id,  "SetDirection.  ID  of  train*'); 
if  (!p)  continue; 

p  =  Getlnt(p,  &neH_dir, 

"Nes  direction  (+l  for  front=head,  -1  for  front=tail,  0  to  toggle)' 
if  (!p)  continue; 

/♦  all  arguments  successfully  obtained  ♦/ 

SetDirection(train_id,  new.dir); 
break; 

} 

case  EMERGENCY.STOP : 

■C 

int  train_id;  /*  identifier  of  the  train  */ 

p  =  Getlnt(p,  &train_id,  "EmergencyStop,  ID  of  tram  to  stop"); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 

EmergencyStop(train_id) ; 
break; 

> 

case  STATION.STOP; 

int  train_id;  /■»  identifier  of  the  train  */ 
enum  StationStopMode  new.val; 

p  =  GetIntCp,  4train_id,  "StationStop.  ID  of  train"); 
if  (!p)  continue; 

sprintf (prompt,  "New  mode  ('/,d  =  disabled,  */,d  =  enabled)". 
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SS.DISABLED,  SS_ENABLED); 
p  =  Getlnt(p,  ftnes_val,  prompt); 

/*  all  arguments  successfully  obtained  ♦/ 

StationStop(train_id,  n,eB_val); 
break; 

} 

case  GET.BLQCK.OCCUPANCY ; 

int  block_id;  /*  identifier  of  the  block  ♦/ 

enum  Occupancy  occ;  /*  return  value  from  the  query  */ 

p  =  GetIntCp,  i;block_id,  "GetBlockOccupancy .  ID  of  block"); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 
occ  =  GetBlockOccupancy(block_id) ; 
if  (-cc  ==  OC.FREE) 

printf ( "Block ‘/,d  is  FREE  (unoccupied) . \n",  block_id); 
else  if  (occ  ==  OC.OCCUPIED) 

printf  ("Block  y.d  is  OCCUPIED .  \n" ,  block_id); 
else  /*  occ  ==  OC.ERROR  */ 

printf  ("Unable  to  obtain  occupancy  for  block  */,d\n",  block_id) ; 
bresik; 

> 

case  GET_SWITCH_PCSITION: 

{ 

int  block.id;  /♦  identifier  of  the  switch  block  */ 
enum  SwitchPosit  posit;  /*  return  value  from  the  query  •/ 

p  =  Getlnt(p,  ftblock_id,  "GetSwitchPosition.  ID  of  switch  block"); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 

posit  =  GetSwitchPosition(block_id) ; 

if  (posit  ==  SP.STRAIGHT) 
printf  ("Switch  block  '/.d  is  STRAIGHTNn",  block.id); 
else  if  (posit  ==  SP_TURHED) 

printf  ("Switch  block  '/,d  is  TURFED\n",  block.id) ; 
else  if  (posit  ==  SP .UNDEFINED) 
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prints ("Switch  block  V.d  has  UNDEFINED  positionNn",  block.id) ; 
else  /•  posit  ==  SP.ERROR  ♦/ 

prints ("Unable  to  obtain  position  oS  switch  block  7,d\n",  block_id); 


break; 

} 

case  GET.TRAIN.STATUS: 

•C 

int  train_id;  /•  identiSier  oS  the  train  */ 

enmn  TrainStatus  status;  /*  return  value  Srom  the  query  */ 

p  =  Getlnt(p,  atrain.id,  "GetTrainStatus .  ID  oS  train"); 
is  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 

status  =  GetTrainStatus(train_id) ; 

if  (status  ==  TS.CRASHED) 
printf  ("Train  ‘/.d  has  CRASHED \n",  train.id); 
else  if  (status  ==  TS.RUNHIHG) 
printf  ("Train ’/.d  is  RUKBIKQ\n",  train.id) ; 
else  /*  status  ==  TS.ERROR  •/ 

printf  ("Unable  to  obtain  status  of  train  '/,d\n",  train.id); 
break; 

} 

case  GET.TRAIN.HOTION: 

int  train.id;  /*  identifier  of  the  train  */ 

enum  TrainMotion  notion;  /*  return  value  from  the  query  ♦/ 

p  =  Getlnt(p,  atrain.id,  "GetTrainMotion.  ID  of  train"); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  ♦/ 

motion  =  GetTrain)1otion(train_id) ; 

if  (motion  ==  TH.STOPPED) 
printf  ("Train  y.d  is  ST0PPED\n",  train.id); 
else  if  (motion  ==  TM.MDVING) 
printf  ("Train  '/,d  is  MQVIHG\n",  train.id); 
else  /*  motion  ==  TM.ERROR  */ 

printf  ("Unable  to  obtain  motion  information  for  train  '/,d\n", 
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train.id) ; 
break; 

} 

case  SET_SEQ_FUMBER: 

{ 

int  new.val;  /*  ney  value  for  sequence  number  */ 
int  seq_num;  /*  return  value  from  SetSeqNumber  */ 

p  =  Getlnt(p,  &neH_val,  "SetSeqNumber.  Ne»  sequence  number  value"); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  »/ 
seq_num  =  SetSeqNumber(new_val); 

printf ("Current  sequence  number  value:  */,d\n",  seq.num); 
break; 

} 

case  NEW.SEQ.NUMBER; 

< 

int  seq_num;  /*  return  value  from  NesSeqNumber  */ 
seq_num  =  NevSeqNumber ( ) ; 

printf  ("Current  sequence  number  value:  '/,d\n",  seq_nam) ; 
break; 

> 

case  QUIT: 

•C 

chcir  confirm [MAXLINE+l] ;  /*  confirmation  string  */ 

printf ("Quit.  Are  you  sure  you  want  to  quit?\n  (y/n,  default  y)  "); 
gets (confirm) ; 

/*  confirmation  response  has  been  received  */ 

if  (*confirm  ==  ’\0’  II  fconfirm  ==  ’y’  II  *confirm  ==  ’Y') 
exit  (NORMAL); 
break; 

> 

case  HELP: 
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struct  command  ♦cp;  /•  pointer  into  comraand.ta'ble  ♦/ 

print! ("y,-34s‘/.s\n - \n"  , 

"entry",  "ACI  command"); 
for  (cp  =  command.table;  cp->code;  cp++)  { 

print! ("•/.'•4s'/.-30s'/.s\n",  cp->code,  cp->args,  cp->name); 

} 

break; 

> 

default : 

print!  ("Unrecognized  commaind  \'7.s\"\nEnter  for  belpNn" ,  buff); 
break; 

>: 

> 

> 
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Appendix  C 

Code  Listings:  LLI 

C.l  cpi.h,  Interface  Header  File 

/*  $RCSfile;  cpi.h, v  $  $Ravision:  1.65  $  $Date;  92/11/24  14:41:00  $  •/ 
/*  cpi.h  —  cpi  message  formats.  */ 

/*  This  file  automatically  generated  by  m4  from  cpi.hm  ♦/ 


/*  Messages  for  initial  and  final  communication  with  simulator  •/ 

/*  first  message  for  simulator,  identifying  self  as  a  CPI  client  •/ 
#define  MSG_CPI_IKIT  "CPI  •/.s’/.'/." 

#define  HSG.CPI.INIT.ARGC  1 

#define  CreateMsgCPIInit (buff ,  str)  sprintf (buif ,  HSG_CPI_INIT,  (str)) 
#define  PaxseHsgCFIInit(buff ,  str)  sscanf(buff,  MSG_CPI_I11IT,  (str)) 


/*  standard  acknowledgement  message  format;  client  ID  is  return  value  */ 
#define  MSG.ACK  "ack  '/.s*/.‘/." 

#define  HSG_ACK_ARGC  1 

#define  CreateHsgAck(buff ,  str)  sprintf (buff ,  MSG_ACK,  (str)) 

#define  PaxseMsgAck(buff ,  str)  sscanf(buff,  MSG_ACK,  (str)) 


/♦  simulator  sends  the  following  message  to  all  clients  upon  normal  exit  */ 
^define  MSG_qUIT_ALL  "QUIT_ALL  V.sVf" 

#define  MSG_QUIT_ALL_ARGC  1 

#<efine  CreateHsgQuit All (buff ,  str)  sprintf (buff ,  MSG.QUIT  .ALL,  (str)) 


(.■) 


#define  ParseHsgQuitAli(buff ,  str)  sscanf(buff,  MSG_QUIT_ALL,  (str)) 


/  *  if***  **********’***’**************************•**•******»***»**  »*•****/ 

/*  Messages  for  configuration  doHnload,  RAB  and  JG  4/90  rev  5/91  */ 

#define  MSG_CPI_DOWNLD_REqUEST  "CPI  Donnld  request  from  '/.s'/.'/." 

#define  MSG_CPI_DOWIfLD_REqUEST_ARGC  1 
#define  CreateMsgCPIDounldBequestCbuff ,  str)  \ 
sprintf(buff ,  MSG_CPI_DOWr.r_REqUEST,  (str)) 

#define  Pars eMsgCPIDosnldRequest (buff ,  str)  \ 
sscanf(buff,  MSG_CPI_DOWNLD_REqUEST,  (str)) 


#define  MSG.CPI.DOWRLD.GENERAL  ”C  */.d  ,*/.d,*/.lf  ,'/.lf  . ’/.If  ,‘/.d.‘/.lf  #" 
typedef  struct  i 

int  block.ct,  train_ct;  /•  number  of  blocks  and  trains  in  layout  */ 
double  acc,  eraer.acc;  /*  standard  and  emergency  stop  acceleration  rates  */ 
double  switch.time;  /*  time  required  for  switch  block  to  change  posit  */ 
int  voting_quorum;  /*  number  of  agreeing  commands  required  for  an  action  •/ 
double  voting.window;  J*  time  limit  after  which  commands  expire  */ 
y  MsgCPIDownldGeneral ; 

#define  MSG_CPI_DOWRLD.GENERAL.ARGC  7 

#define  MsgCPIDownldGeneralArgs(baff ,  datap)  (buff,  MSG.CPI.DOWRLD. GENERAL ,  \ 
datap->block_ct  ,  datap->train_ct  ,  datap->acc  ,  datap->emer_acc  ,  \ 
datap->switch_time  ,  datap->voting_quorum  ,  datap->votirg_window  ) 

#define  CreateMsgCPIDownldGeneralCbuff ,  datap)  \ 
sprintf  HsgCPIDownldGeneralArgs(buff ,  (datap)) 

#define  ParseMsgCPIDownldGeneral(buff ,  datap)  \ 
sscanf  MsgCPIDownldGeneralArgs(buf f ,  k(datap)) 


#define  KSG.CPI.DOWRLD.TRAIB  "T’/.d.’/.H .’/.d.V.H ,V.d .‘/.If #" 
typedef  struct  { 

int  train.id;  /*  numerical  name  of  this  train  ♦/ 
double  length;  /*  length  of  train  ♦/ 

int  head.block;  /*  block.id  for  block  holding  train  head  */ 
double  head.offset;  /*  offset  within  head.block  of  train  head  */ 
int  tail.block;  /♦  block.id  for  block  holding  train  tail  */ 
double  tail.offset;  /*  offset  within  tail.block  of  train  tail  */ 
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}  MsgCPIDownldTrain; 


#deline  MSG_CPI_DOWKLD_TRAIN_ARGC  6 

#deliixe  MsgCPIDoonldTrainArgsCbufl .  datap)  (buff,  HSG.CPI.DOWNLD.TRAIN ,  \ 

datap->train_id  ,  datap->length  ,  datap->head_block  ,  datap->head_of fset  ,  \ 
datap->tail_block  ,  datap->tail_ollset  ) 

#deline  CreateMsgCPIDoHnldTrainCbuff ,  datap)  \ 
sprintf  MsgCPIDoHnldTraiaArgs(buff ,  (datap)) 

#define  ParseMsgCPIDoHnldTrain(bufl ,  datap)  \ 
sscaal  MsgCPIDosnldTrainArgsCbufl ,  ft(datap)) 


#deline  MSG_CPI_DOWNLD_BLOCK  "By.d.y.ll .'/.d.'/.lf .‘/.ll ,*/.d#" 
typedel  struct  { 

int  block.id;  /*  numerical  name  of  this  block  •/ 

double  length;  /*  length  of  the  block  in  meters  */ 

int  type;  /*  code  for  type  classification  of  this  block  */ 

double  mcLX.speed,  min.speed;  /*  speed  above/beloB  which  derailment  occurs*/ 

double  sta_stop_speed;  /*  highest  station  stop  speed - sta  blocks  only  */ 

int  cross.id;  /*  id  for  the  cross  block — for  cross  subblocks  only  •/ 

}  MsgCPIDosnldBlock; 

#define  MSG_CPI_DOWIILD.BLOCK.ARGC  7 

#define  MsgCPIDownldBlockArgsCbuff .  datap)  (buff,  HSG.CPI.DOWRLD.BLOCK,  \ 
datap->block_id  ,  datap->length  ,  datap->type  ,  datap->max_speed  ,  \ 
datap- >min_speed  ,  datap->sta_stop_speed  ,  datap->cross_id  ) 

#define  CreateMsgCPIDoBnldBlock(buff ,  datap)  \ 
sprintf  MsgCPIDo»nldBlockArgs(buff ,  (datap)) 

#define  ParseMsgCPIDoBnldBlock(bufl,  datap)  \ 
ssccinf  MsgCPIDoBnldBlockArgs(buff ,  ft(datap)) 


^define  MSG.CPI.DOWNLD.LINK  "L'/.d.’/.d.y.d.y.d.y.d#" 
typedef  struct  { 

int  block.id;  /*  numerical  name  of  this  block  •/ 

int  type;  /♦  code  for  type  classification  of  this  block  */ 

int  tail,  headl,  head2;  /*  block.ids  for  adjoining  blocks  */ 

}  MsgCPIDosnldLink; 

#define  MSG.CPI.DOWnuD.LINK.ARGC  fe 

#define  MsgCPIDoBnldLiiikArgs(buff ,  datap)  (buff,  MSG.CPI.DOWNLD.LINK.  \ 


datap->block_id  ,  datap->type  ,  datap->tail  ,  datap->headl  ,  datap->head2  ) 

#define  CreateMsgCPIDovnldLink(buff ,  datap)  \ 
sprint!  MsgCPIDownldLinkArgsCbuf! ,  (datap)) 

#define  ParseMsgCPIDosnldLinkCbu!! ,  datap)  \ 
sscanf  MsgCPIDounldLinkArgsCbu!! ,  &(datap)) 


/*  The  end  of  an  cpi  config  download  may  be  recognized  by  searching  for 

CPI_D'^VNLD_TERI1  beginning  CPI_DOWHLD_TERM_DFFSET  from  final  char  received*/ 

#define  CPI_DOWNLD_TERH  ’D’ 

#define  CPI_DOWNLD_TERM_OFFSET  -4 

#define  MSG_CPI_DaW!!rLD_DaNE  "D  ‘/.d#" 

#define  MSG_CPI_DaWNLD_DQNE_ARGC  1 
#define  CreateMsgCPIDownldDoneCbuff ,  val)  \ 
sprintfCbuff ,  MSG_CPI_DQWKLD_DDSE,  (val)) 

#define  Pars eMsgCPIDonnldDone (buff ,  val)  \ 
sscanfCbuff,  MSG_CPI_DQWNLD_DOHE,  4(val)) 


********  ***********  ******»4i«*«4i******4i**«**i«>**  *>«****«*»«*<•'»**  ****iti»/ 

/*  Commands  */ 

#define  MSG_CPI_SET_SWITCH  •'Xh'/.d,y.d:'/,d;'/,d#" 
typedef  struct  { 

int  client_id:  /*  unique  identifier  for  this  client  ♦/ 
int  seq_num;  /*  label  for  this  command  •/ 
int  block_id;  /*  simulator  block  number  */ 

int  neo_posit;  /*  new  soitch  position — 0  for  straight  and  1  for  turned  •/ 

}  MsgCPISetSwitch; 

#define  11SG_CPI_SET_SWITCH_ARGC  4 

#define  MsgCPISetSwitchArgs(buf f ,  datap)  (buff,  MSG_CPI_SET_SWITCH ,  \ 
datap->client_id  ,  datap->seq_num  ,  datap->block_id  ,  datap- >new_posit  ) 

#define  CreateMsgCPISetSwitch(buff ,  datap)  \ 
sprintf  HsgCPISetSwitchArgSvluff ,  (datap)) 

#define  ParseMsgCPISetSwitch(buff ,  datap)  \ 
sscanf  MsgCPISetSwitchArgs(buff ,  & (datap)) 
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tdefine  MSG_CPI_ACCEL  ’'Xa%d.‘/.d;y.d;y.ll#" 
typedef  struct  { 

int  client_id:  /*  unique  identifier  for  this  client  ♦/ 
int  seq_nuin:  /♦  label  for  this  command  »/ 
int  train_id:  /•  simulator  train  niuaber  */ 
double  duration:  /♦  time  to  accelerate  in  seconds  ♦/ 

}  MsgCPlAccel; 

#define  MSG_CPI_ACCEL_ARGC  4 

#def ine  MsgCPIAccelArgs(buff ,  datap)  (buff,  MSG_CPI_ACCEL,  \ 

datap->client_id  ,  datap->seq_nuai  ,  datap->train_id  ,  datap->duration  ) 

#define  CreateHsgCPIAccel(buf f ,  datap)  sprintf  MsgCPIAccelArgs (buf f ,  (datap)) 
#define  ParseMsgCPIAcceKbuff ,  datap)  sscanf  MsgCPIAccelArgs (buff ,  ft(datap)) 


#define  HSG_CPI_DECEL  "Xd'/.d , %d : ‘/.d : '/.If #" 
typedef  struct  { 

int  client.id;  /♦  unique  identifier  for  this  client  ♦/ 
int  seq.num;  /•  label  for  this  command  ♦/ 
int  train. id;  /*  simulator  train  number  •/ 
double  duration;  /*  time  to  decelerate  in  seconds  •/ 

}  MsgCPIDecel; 

#define  MSG.CPI.DECEL.ARGC  4 

#define  MsgCPIDccelArgs(buff ,  datap)  (buff,  MSG.CPI.DECEL,  \ 

datap->client_id  ,  datap->seq_niun  ,  datap->train_id  ,  datap->duration  ) 

#define  CreateHsgCPIDecel(buff ,  datap)  sprint!  MsgCPIDecelArgs(bulf ,  (datap)) 
#define  ParseMsgCPIDecel(buff ,  datap)  sscanf  MsgCPIDecelArgs(buff ,  ft(datap)) 


#define  MSG.CPI.SET.SPEED  •■Xvy.d,y.d:y.d:y.lf#" 
typedef  struct  { 

int  client.id;  /•  unique  identifier  for  this  client  */ 
int  seq.niun;  /•  label  for  this  command  */ 
int  train.id;  /*  simulator  train  number  */ 
double  goal.speed;  /♦  now  desired  velocity  for  the  train  */ 

}  MsgCPISetSpeed; 

Odefine  MSG.CPI.SET.SPEED.ARGC  4 

#define  MsgtPISetSpeedArgs(buff ,  datap)  (buff,  MSG.CPI.SET.SPEED,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train.id  ,  datap->goal. speed  ) 
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#d8line  CreateMsgCPISetSpeed(bull ,  datap)  \ 
sprint!  HsgCPISetSpeedArgs(bnll ,  (datap)) 
#de!ine  ParseMsgCPISetSpeed(buff ,  datap)  \ 
sscanf  MsgCPISetSpeedArgsCbuff ,  A(datap)) 


#defiue  MSG_CPI_SET_DIR  •'Xf*/.d,*/.d:'/.d:*/.d#" 
typedef  struct  { 

int  client_id:  /*  unique  identifier  lor  this  client  •/ 
int  seq.num;  /♦  label  lor  this  conunand  ♦/ 
int  train_id;  /*  simulator  train  number  ♦/ 
int  nes.dir;  /•  indicator  ol  new  train  direction  */ 

}  MsgCPISetDir : 

#deline  MSG_CPI_SET_DIR_ARGC  4 

#deline  MsgCPISetDirArgsCbull,  datap)  (bull,  MSG_CPI_SrT_DIR ,  \ 

datap->client_id  ,  datap-> seq.num  ,  datap->train_id  ,  datap->nev_dir  ) 

#define  CreateMsgCPISetDir(bufl,  datap)  sprintl  MsgCPISetDirArgs(bull ,  (datap)) 
#define  ParseHsgCPISetDir(bull ,  datap)  ssceinl  MsgCPISetDirArgs (bull ,  ft (datap)) 


#deline  MSO_CPI_EHER_STOP  "Xe’/,d,‘/.d:y.d#" 
typedef  struct  {. 

int  client.id;  /*  unique  identifier  for  this  client  */ 
int  seq.num;  /*  label  lor  this  command  */ 
int  train. id;  /*  simulator  train  number  •/ 

}  MsgCPIEmerStop; 

#deline  MSG_CPI.EMER_STOP.ARGC  3 

Adeline  MsgCPIEmerStopArgs(bull,  datap)  (bull,  MSG.CPI.EMER.STDP,  \ 
datap->client_id  ,  datap- >seq_num  .  datap->^rain_id  ) 

#deline  CreateMsgCPIEmerStop(bull,  datap)  \ 
sprint!  MsgCPIEmerStopArgs(bull ,  (datap)) 

#define  ParseHsgCPIEmerStop(bull ,  latap)  \ 
sscanf  MsgCPIEmerStopArgs(bull,  ft(datap)) 


#define  MSG.CPI.STA.STOP  •'Xs’/,d,'/,d:'/.d:y.d#" 
typedef  struct  { 

int  client. id;  /*  unique  identifier  lor  this  client  */ 
int  seq.num;  /*  label  lor  this  command  */ 
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int  train._id;  /*  simulator  train  number  */ 
int  new_val;  /*  0  to  disable  and  1  to  enable  •/ 

}  MsgCPIStaStop; 

tdeline  MSG_CPI_STA_STaP_ARGC  4 

tdefine  MsgCPIStaStopArgs(buff ,  datap)  (buff,  MSG_CPI_STA_STOP,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->neH_val  ) 

#define  CreateHsgCPIStaStop(buff ,  datap)  \ 
sprintf  MsgCPIStaStopArgs(buff ,  (datap)) 

#define  ParseMsgCPIStaStop(buff,  datap)  sscanf  MsgCPIStaStopArgs(buff ,  ft(datap)) 


/*«**«4i4>*****4<**«**4i******«««*i**4>il>****4i****««4<»***««*«**«»»«**4>*  •»•«*•»*«**»/ 

/♦  Queries  */ 

#define  MSG_CPI_BLOCK_OCC  "Xo*/.d.‘/.d:*/.d#" 
typedef  struct  •{ 

int  client.id;  /*  unique  identifier  for  this  client  ♦/ 
int  seq.num;  /♦  label  for  this  command  */ 
int  block. id;  /*  simulator  block  number  */ 

}  MsgCPIBlockOcc; 

#define  MSG.CPI.BLOCK.OCC.ARGC  3 

#define  HsgCPIBlockOccArgs(buff ,  datap)  (buff,  MSG.CPI.BLOCK.DCC,  \ 
datap->client_id  ,  datap->seq_num  ,  datap->blcck_id  ) 

#define  CreateMsgCPIBlockOcc(buff ,  datap)  \ 
sprintf  MsgCPIBlockOccArgs(buff ,  (datap)) 

#define  ParseMsgCPIBlockOcc (buff ,  datap)  \ 
sscanf  MsgCPIBlockOccArgs(buff ,  ft(datap)) 


#define  MSG.CPI.SWITCH.POSIT  •■Xn‘/,d,*/.d;y.d#" 
typedef  struct  { 

int  client.id;  /♦  unique  identifier  for  this  client  */ 
int  seq.num;  /*  label  for  this  command  */ 
int  block. id;  /*  simulator  block  number  •/ 

}  MsgCPISwitchPosit ; 

#define  MSG.CPI.SWITCH.POSIT. ARGC  3 

#define  MsgCPISwitchPositArgs (buff ,  datap)  (buff,  MSG.CPI.SWITCH.POSIT,  \ 
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datap->client_id  ,  datap->seq_niua  ,  datap->block_id  ) 


#deline  CreateMsgCPISwitchPo: it(buff ,  datap)  \ 
sprintf  MsgCPISwitchPositAigs(bull ,  (datap)) 
#deline  ParseMsgCPISwitchPositCbull.  datap)  \ 
sscanf  MsgCPISBitchPositArgs(buff ,  4(datap)) 


#define  MSG_CPI_TRAIN_STATUS  ■•Xt*/.d,*/.d:‘/.d#'* 
typedef  struct  { 

int  client_id;  /•  unique  identifier  for  this  client  ♦/ 
int  seq_num;  /♦  label  for  this  command  •/ 
int  txain_id;  /*  simulator  train  number  ♦/ 

>  HsgCPITrainStatus; 

#define  MSG.CPI_TRAIR_STATUS_ARGC  3 

#define  MsgCPITrainStatusArgsCbuff ,  datap)  (buff,  MSG_CPI_TRAIH_STATUS .  \ 
datap->client_id  ,  datap- >seq_num  ,  datap->train_id  ) 

#define  CreateMsgCPITrainStatus(baff ,  datap)  \ 
sprintf  HsgCPITrainStatusArgs(bulf ,  (datap)) 

#define  ParseMsgCPITrainStatus(buff ,  datap)  \ 
sscanf  MsgCPITrainStatusArgs(buff ,  ft(datap)) 


^define  MSG_CPI_TRAIK_HOTIOR  "Xm*/,d,*/,d;'/,d#" 
typedef  struct  { 

int  client.id;  /*  unique  identifier  for  this  client  */ 
int  seq.num;  /•  label  for  this  command  ♦/ 
int  train_id;  /*  simulator  train  number  •/ 

>  HsgCPITrainMotion; 

#define  HSG.CPI.TRAIH.HOTIOH.ARGC  3 

#define  MsgCPITrainMotionArgs(buff ,  datap)  (buff,  MSG_CPI_TRAIH_MCTIOB ,  \ 
datap->client_id  ,  datap- >seq_nura  ,  datap->train_id  ) 

#define  CreateMsgCPITrainMotion(buff ,  datap)  \ 
sprintf  MsgCPITrainMotionArgs(buff ,  (datap)) 

#define  ParseMsgCPITrainMotion(buff ,  datap)  \ 
sscanf  MsgCPITrainHotionArgs(buff ,  4(datap)) 
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C.2  aci.c,  Example  Using  the  LLI  Interface 

/*  $RCSfile:  aci.c, v  $  $Revision:  1.1  $  $Date:  92/07/17  10:58:20  $  */ 

/*  aci.c  —  implementation  of  the  Automatic  Control  Interface  of  the  CPI 
R.  Broun  6/91,  based  on  specifications  and  earlier  versions  •/ 

#include  <stdio.h>  /*  for  standard  error  and  NULL  ♦/ 
tinclude  <sys/types .h>  /•  required  for  acisys.h  */ 

#include  "cpi.h"  /*  lou-level  interface  of  the  CPI  */ 

#include  "aci.h"  /•  for  data  type  definitions  ♦/ 

#include  "acisys.h"  /♦  operating  system-specific  routines  */ 

#define  BUFFSIZE  200  /*  mziximum  size  of  a  message  */ 

#define  RETBY_INTERVAL  5.0  /♦  seconds  between  retries  for  ConnectToSim  */ 

#define  QUERY.TIMEQUT  5.0  /*  seconds  before  giving  up  on  a  query  response  ♦/ 

#define  EPSILON  0.0001  /*  tolerance  for  floating  point  comparisons  ♦/ 

LayoutData  layout.da.a,  ♦Idp  =  Alayout_data; 

/♦  data  structure  for  storing  the  information  passed  in  the  download  */ 
int  chan;  /♦  socket  for  communicating  with  simulator  */ 
int  client_id;  /•  identifier  for  this  client,  obtained  from  simulator*/ 
int  seq.num  =  0;  /♦  sequence  number,  for  voting  purposes  •/ 


**********  *:»**»**  ***»»»«««**/ 

/♦  SendInitMossage  sends  the  simulator  the  initialization  message  for  this 
application.  Returns  nonzero  on  success,  zero  on  failure. 

RAB  11/30/89  */ 


int 

SendInitMessage(chan,  string) 

int  chan;  /*  channel  descriptor  for  communication  with  simulator  */ 
char  stringCJ;  /•  string  to  send  as  part  of  the  message  to  sim  */ 

{ 

char  buff [BUFFSIZE] ;  /♦  buffer  for  init  message  and  ack  */ 
int  n;  /♦  length  of  received  init  message  */ 

char  client_id_string [BUFFSIZE] ;  /*  string  representing  client.id  •/ 

/*  send  the  initialization  message  •/ 
sprintf (buff ,  HSG_CPI_IIIT,  string); 
if  (SendMsgCchan,  buff,  strlen(buff ))  <  0)  { 
perror(''SendInit}!essage:  SendMsg  failed"); 
return  (0) ; 


} 

/♦  wait  for,  verify  acknoolcdgement  */ 

if  ((n=RecvMsg(chan,  buff,  BUFFSIZE))  <  0)  i 
perror('’SeiidInitHessage;  can’t  receive  acknouledgement") ; 
return  (0); 

> 

buff [a]  =  ’NO': 

if  (sscanf (buff ,  HSG_ACK,  client_id_string)  !=  1)  { 

fprintf (stderr ,  “SendInitMessage :  expected  ack,  received  \"'/,s\"\n",  buff); 
return  (0) ; 

> 

sscanf  (client_id_string,  ’"/,d",  Stclient_id) ;  /♦  extract  unique  id  */ 

return  (1); 

> 


/* 

We  trust  the  simulator’s  download...  */ 


LayoutData  • 

GetDounloadChostname,  simnum,  progname,  timeout) 

char  *hostneuae:  /*  machine  running  a  simulation  ♦/ 
int  simnum;  /*  identifies  a  running  simulation  ♦/ 
char  *progname;  /*  name  of  invoking  program  ♦/ 
double  timeout;  /*  in  seconds  ♦/ 

{ 


static  GetDownloadSucceeded  =  0;  /♦  set  non-zero  on  first  successful  call  */ 

char  buff [BUFFSIZE] ;  /♦  buffer  for  holding  one  message  */ 

union  { 

MsgCPlDoHUldGeneral  gen;  /♦  for  unpacking  message  of  general  attributes  */ 

MsgCPIDounldBlock  block;  /*  lor  unpacking  message  of  block  attributes  ♦/ 

MsgCPIDownldLink  link;  /*  for  unpacking  message  of  block  attachments  */ 

MsgCPIDownldXrain  train;  /♦  lor  unpacking  message  ol  train  attributes  ♦/ 

int  val;  /*  for  receiving  integer  value  passed  with  MsgCPIDownldDone  */ 

>  msg; 

int  incomplete;  /*  non-zero  if  the  dovnload  is  found  to  be  incomplete  */ 
int  recv_msg_status ;  /•  return  value  from  RecvMsg  */ 

int  i;  /*  loop  control  */ 


84 


if  (GetDownloadSucceeded)  i 

fprintf (stderr,  "GetDoHnload  has  already  been  called  successfullyNn" ) ; 
return  (NULL); 

> 

/*  there  have  been  no  prior  successful  calls  */ 
if  (timeout  <=  0)  { 

fprintf  (stderr,  "GetDosnload:  Non-positive  timeout  y,.lf\n'',  timeout); 
return  (NULL); 

} 

/*  valid  timeout  was  specified  */ 

if  (! •hostname)  { 

GetLocalHost(buff ,  sizeof (buff )) ; 
hostname  =  buff ; 

> 

while  ((chan  =  ConnectToSim(hostname,  simnum))  ==  -1)  { 
timeout  -=  RETRY.INTERVAL; 
if  (timeout  <  EPSILON)  { 

fprintf (stderr,  "GetDownload:  Could  not  connect  to  simulatorVn" ) ; 
return  (NULL); 

}  else  •{ 

fprintfC  retrying ...  \n") ; 

Sleep(RETRY.INTERVAL) ; 

} 

> 

/•a  connection  to  the  desired  simulation  has  been  established  */ 

if  ( !SendInitHessage(chan,  progname))  { 

fprintf (stderr,  "GetDownload:  Could  not  send  init  messageXn" ) ; 
CloseChan(chan) ; 
return  (NULL); 

> 

/*  CPI  initialization  message  has  been  sent  and  acknowledged  */ 

CreateHsgCPIDownldRequest (buff ,  progname ) ; 
if  (SendMsg(chan,  buff,  strlen(buff ))  <  0  )  { 
perror("MsgCPIDownldRequest  SendMsg  failed"); 

fprintf (stderr,  "GetDownload:  Could  not  send  request  for  downloadXn") ; 
CloseChan(chain) ; 
return  (NULL); 

} 
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/*  Download  has  been  requested. 

The  simulator’s  expected  response  is  the  download  itself.  */ 


/•  receive  download  */ 

/*  invar;  all  CPIDownld  messages  so  far  have  been  parsed  ■*/ 
while  ((recv_msg_status  =  RecvDownldMsg(chan,  buff,  BUFFSIZE))  >  0 
ParseMsgCPIDownldDone(buff ,  ms-.val)  f= 

MSG_CPI_DOWNLD_DONE_ARGC)  { 

/♦  new  message  of  length  recv_msg_status  that  is  not  DownldDone 
has  been  received  */ 

buff [recv_msg_status]  =  ’\0’; 

if  (ParseMsgCPIDownldGeneral(buff ,  ftmsg.gen)  == 

HSG_CPI_DOWHLD_GENERAL_ARGC)  { 
ldp->block_ct  =  msg. gen. block. ct; 
ldp->train_ct  =  msg.gen.train.ct; 
ldp->acc  =  rasg.gen.acc; 
ldp->emer_acc  =  msg.gen. emer.acc; 
ldp->switch_time  =  msg.gen. switch.time; 
ldp->voting_quorum  =  msg.gen.voting.quorum; 
ldp->voting_window  =  msg. gen. voting. window; 

if  (ldp->block.ct  >  MAX.BLOCKS  I  I  ldp->train.ct  >  MAX.TRAINS)  { 
fprintf (stderr, 

"GetDownload:  MAX.TRAIRS  ('/,d)  or  MAX.BLOCKS  (*/.d)  too  small\n" , 
MAX.TRAINS,  MAX.BLOCKS); 
return  (NULL); 

} 

>  else  if  (ParseMsgCPIDownldBlock(buff ,  ftmsg. block)  == 
MSG.CPI.DOWNLD.BLOCK.ARGC)  { 
int  index  =  rasg. block. block. id  -  1; 

/♦  this  block’s  index  in  ldp->blocksn  •/ 

ldp->blocks [index] .block.id  =  msg. block. block.id; 
ldp->blocks [index] .length  =  msg. block. length; 
ldp->blocks [index] .type  =  (enum  BlockType)  msg. block. type; 
ldp->blocks [index] .max. speed  =  msg. block. max. speed; 
ldp->blocks [index] .min.speed  =  msg. block. min.speed; 
if  ((enum  BlockType)  msg. block. type  ==  BT.STATION) 
ldp->blocks [index] .t.st .sta_stop_speed  =  msg. block. sta. stop. speed; 
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if  ((enum  BlockType)  msg .block. type  ==  BT_CRDSS) 
ldp->blocks [index] .t . cr . cross.id  =  msg. block. cross.id; 

>  else  if  (ParseMsgCPIDoHnldLink(buff ,  ftmsg.link)  == 
MSG_CPI_D0WNLD_LI1IK_ARGC)  { 
int  index  =  msg .link. block_id  -  1; 

/*  this  block’s  index  in  ldp->blocks []  ♦/ 

switch  (ldp->blocks [index] .type)  { 
case  BT_REGULAR: 
case  BT_STATIQN; 
case  BT_CR0SS; 

ldp->blocks [index] .t .rg. tail  =  msg. link. tail ; 
ldp->blocks [index] .t.rg. head  =  msg. link. headl; 
break; 

case  BT_JOIS: 

ldp->blocks [index] .t.jn. tail  =  msg. link. tail; 
ldp->blocks [index] .t.jn. headl  =  msg .link. headl ; 
ldp->blocks[index] .t. jn.head2  =  msg. link. head2; 
break; 

case  B-^.SWITCH: 

ldp->blocks [index] .t . sw .tail  =  msg. link. tail; 
ldp->blocks [index] .t . sw. straight  =  msg. link. headl ; 
ldp->blocks [index] .t.sw. turn  =  msg. link. head2; 
break; 

> 

}  else  if  (ParseHsgCPIDownldTrain(buff ,  ftmsg. train)  == 
IlSG_CPI_DOWHLD_TRAm_ARGC)  { 
int  index  =  msg. block. block_id  -  1; 

/*  this  train’s  index  in  ldp->trains []  ♦/ 

ldp->trains [index] .train_id  =  msg.train.train.id; 
ldp->trains [index] . length  =  msg. train. length; 
ldp->trains [index] .head. block  =  msg. train. head.block; 
ldp->trains [index] .head. off set  =  msg. train. head, offset; 
ldp->trains [index] .tail .block  =  msg. train. tail,block; 
ldp->trains [index] .tail. off set  =  msg. train. tail.off set; 

}  else  ■{  /*  unrecognized  message  format  */ 

fprintf (stderr ,  "GetDownload:  Unrecognized  message  from  simulator\n") ; 
fprintf (stderr,  ’"/,s\n",  buff); 
return  (NULL) ; 

} 
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} 


il  (recv_iasg_status  <=  0)  { 

fprintl (stderr,  "GetDoHnload:  Failed  in  attempt  to  receive  a  messageXn"); 
return  (NULL) ; 

> 

/*  There  sere  no  failures  to  receive  a  message,  and 

all  received  messages  have  been  successfully  parsed  and  data  stored  in 
layout_data,  and  one  Done  message  was  received  ♦/ 


/•  check  to  see  whether  download  was  complete  */ 
incomplete  =  0; 

/*  we  will  assume  that  all  of  the  fields  from  MsgCPIDownldGeneral  were 
received  and  stored  properly  in  layout_data  if  block_ct  is  nonzero  */ 
if  ( !ldp->block_ct)  ■( 

fprintf (stderr ,  "GetDownload:  incomplete  download  (missing  General) \n" ) ; 
incomplete++; 

} 

for  (i  =  0;  i  <  ldp->block_ct:  i++)  { 

/*  we  will  assume  that  all  of  the  fields  from  MsgCPIDownloadBlock  were 
received  and  stored  properly  in  layout_data  il  block.id  is  nonzero  */ 
if  ( ! ldp->blocks [i] .block_id)  { 

fprintf  (stderr,  "GetDownload:  incomplete  download  (missing  Block  '/,d)\n" 
i  +  1) : 
incomplete++ ; 

> 

/♦we  will  assume  that  all  of  the  fields  from  MsgCPIDownloadLink  were 
received  and  stored  properly  in  layout.data  if  tail  is  nonzero  ♦/ 
if  ( !ldp->blocks[i] .t.rg.tail)  { 

fprintf  (stderr,  "GetDownload:  incomplete  download  (missing  Link  '/,d)\n'', 

i  +  1) : 

incomplete++; 

} 

} 

for  (i=0;  i  :  ldp->train_ct;  i++) 

/♦we  will  assume  that  all  of  the  fields  from  MsgCPIDownloadTrain  were 
received  and  stored  properly  in  layout_data  if  train_id  is  nonzero  •/ 
if  ( ! ldp->trains [i] . train_id)  { 

fprintf  (stderr ,  "GetDownload:  incomplete  download  (missing  Train  '/,d)\n" 
i  +  1); 
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iacomplete++ ; 

} 

if  (incomplete) 
return  (NULL); 

/*  a  complete  download  was  successfully  received  */ 

GetDoHnloadSucceeded++ ; 
return  (ftlayout.data) ; 


««****»***•««*  ******4>*  ***«*******•**»*****•*/ 

/*  commands  •/ 
void 

SetSHitch(block_id,  new.posit) 
int  block.id; 
enum  NewPosit  new.posit; 

< 

MsgCPISetSwitch  msg;  /*  data  structure  for  message  construction  ♦/ 
char  buff [BUFFS I ZE] ;  /*  buffer  for  outgoing  message  •/ 

msg . client.id  =  client.id;  /•  identifier  of  this  client  */ 
msg.seq_num  =  seq_num;  f*  voting  sequence  number  ♦/ 
msg.block_id  =  block_id; 
rasg.new_posit  =  (int)  new_posit; 

CreateMsgCPISetSBitch(buff ,  itrasg) ; 
if  (SendHsg(chan,  buff,  strlen(buff ))  <  0)  { 
perror("SetSBitch:  SendHsg  failed"); 

> 


void 

Accelerate(train_id,  duration) 
int  train_id; 
double  duration; 

{ 

HsgCPIAccel  msg;  /♦  data  structure  for  message  construction  */ 
char  buff [BUFFSIZE] ;  /♦  buffer  for  outgoing  message  ♦/ 
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msg.client_id  =  client.id;  /*  identifier  of  this  client  •/ 
msg.seq_num  =  seq_nuni:  /*  voting  sequence  number  */ 
msg.train.id  =  tra:n_id; 
rasg. duration  =  duration; 

CreateMsgCPIAcceKbuff ,  ftmsg); 
if  (SendHsgCchan,  buff,  strlen(buff ))  <  0)  { 
perrorC’Accelerate:  SendHsg  failed"); 

> 


void 

Decelerate (train_id,  duration) 
int  train. id; 
double  duration; 

MsgCPIDecel  msg;  /♦  data  structure  for  message  construction  */ 
char  buf f [BUFFSIZE] ;  /*  buffer  for  outgoing  message  */ 

msg.client.id  =  client.id;  /•  identifier  of  this  client  */ 
msg.seq.num  =  seq.num;  /*  voting  sequence  number  */ 
msg. train. id  =  train. id; 
msg. duration  =  duration; 

CreateMsgCPiDecelCbuff ,  ftmsg); 
if  (SendHsgCchan,  buff,  strlenCbuff ) )  <  0)  { 
perror("Decelerate:  SendHsg  failed"); 

> 


void 

SetSpoedCtrain.id,  goal. speed) 
int  train. id; 
double  goal  speed; 

MsgCPISetSpeed  msg;  /*  data  structure  for  message  construction  ♦/ 
char  buff [BUFFS IZE] ;  /*  buffer  for  outgoing  message  ♦/ 

msg.client.id  =  client. id;  /*  identifier  of  this  client  ♦/ 
msg.seq.num  =  seq.num;  /*  voting  sequence  number  ♦/ 
msg.train.id  =  train.id; 
msg .goal. speed  =  goal. speed; 
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CreateMsgCPISetSpeed(buff ,  Amsg) ; 
if  (SendMsg(chan,  buff,  strlen(buff ) )  <  0)  { 
perror ("SetSpeed;  SendHsg  failed"); 

} 


void 

SetDirectioii(traiu_id,  nes_dir) 
int  train_id; 
int  new_dir; 

MsgCPISetDir  msg;  /*  data  structure  for  message  construction  */ 
char  buff [BUFFSIZE] ;  /*  buffer  for  outgoing  message  •/ 

msg . client_id  =  client_id;  /*  identifier  of  this  client  »/ 
msg.seq.nujn  =  seq_num;  /♦  voting  sequence  number  •/ 
msg.train_id  =  train. id; 
msg.neo.dir  =  neu.dir; 

CreateMsgCPISetDirCbuff ,  ftmsg); 
if  (SendMsgCchan,  buff,  strlen(buff ) )  <  0)  { 
perror("SetDirection:  SendMsg  failed"); 

} 


void 

EmergencyStop(train_id) 
int  train. id; 

MsgCPIEraerStop  msg;  /*  data  structure  for  message  construction  */ 
char  buff [BUFFSIZE] ;  /♦  buffer  for  outgoing  message  */ 

msg.client.id  =  client.id;  /♦  identifier  of  this  client  ♦/ 
msg.seq.num  =  seq.num;  /*  voting  sequence  number  •/ 
msg.train.id  =  train.id; 

CreateMsgCPIEraerStopCbuff ,  Arasg) ; 
if  (SendMsgCchan,  buff,  strlen(buff))  <  0)  { 
perror ("EmergencyStop;  SendMsg  failed"); 

} 
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void 

StationStop(train_id,  neH_val) 
int  train_id: 

enum  StationStopHode  nes.val; 


MsgCPIStaStop  msg;  /•  data  structure  for  message  construction  »/ 
cheir  buff  [BUFFSIZE]  :  /•  buffer  for  outgoing  message  */ 

msg, client_id  =  client_id;  /*  identifier  of  this  client  •/ 
msg.seq_num  =  seq_num;  /•  voting  sequence  number  */ 
msg.train_id  =  train_id; 
msg.new.val  =  (int)  neu.val; 

CreateMsgCPIStaStop(buff ,  ftrasg); 
if  (SendMsg(chan,  buff,  strlen(buff ) )  <  0)  { 
perror("StationStop;  SendMsg  failed"); 

} 


**«*****«*********•»  *»•«***/ 

/•  Queries  ♦/ 


enum  Occupancy 
GetBlockOccupancy (block_id) 
int  block. id; 

{ 

MsgCPIBlockOcc  msg;  /*  data  structure  for  message  construction  */ 
char  buff [BUFFSIZE] ;  /♦  buffer  for  outgoing  message  ♦/ 

int  n;  /*  return  status  from  RecvMsgTiraed  •/ 

msg.client.id  =  client.id;  /*  identifier  of  this  client  *l 
msg.soq.num  =  seq.num;  /*  voting  sequence  number  ♦/ 
msg.block.id  =  block. id; 

CreateMsgCPIBlockOcc(buff ,  ftmsg); 
if  (SendMsg (chan,  buff,  strlen(buff ) )  <  0)  { 
perrorC "GetBlockOccupancy;  SendMsg  failed"); 

} 
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if  ((n  =  RecvMsgTimedCchan,  bu«,  BUFFSIZE,  QUERY.TIKEOUT) )  <  0) 
return  (QC.ERRDR); 

/•  response  successfully  received  from  simulator  and  stored  in  buff  */ 

switch  (buffCo])  { 
case  ’o’;  return  (OC.CCCUPIED) ; 
case  ’f’;  return  (0C_FREE); 
default : 

buffCn]  =  ’\0’; 

fprintf  (stderr,  "GetBlockOccupancy :  unknown  simulator  response  \"’/,s\"\n' 
buff): 

return  (QC.ERRQR) ; 

} 

> 


enum  SwitchPosit 
GetSwitchPosition(block_id) 
int  block. id; 

{ 

MsgCPISwitchPosit  msg;  /•  data  structure  for  message  construction  */ 
char  buff [BUFFSIZE] ;  /*  buffer  for  outgoing  message  ♦/ 

int  n;  /*  return  status  from  RecvMsgTimed  ♦/ 

msg . client.id  =  client.id;  /»  identifier  of  this  client  */ 
rasg.seq.nura  =  seq.nura;  /*  voting  sequence  number  */ 
msg.block.id  =  block.id; 

CreatoMsgCPISwitchPosit (buff ,  ftmsg) ; 
if  (SendMsgCchan,  buff,  strlen(buff ) )  <  0)  { 
pcrror("GetSwitchPosition:  SendMsg  failed"); 

> 

if  ((n  =  RecvMsgTiraedCchan,  buff,  BUFFSIZE,  qUERY.TIMEOUT) )  <  0) 
return  (SP .ERROR); 

/*  response  successfully  received  from  simulator  and  stored  in  buff  ♦/ 

switch  (buffCO])  { 
case  ’s’:  return  (SP.STRAIGHT) ; 
case  ’t':  return  (SP.TURBED); 
case  ’u’:  return  (SP.UNDEFIRED) ; 
default ; 

buff[n]  =  ’\0’: 

fprintf  (stderr ,  "GetSwitchPosition:  unknown  simulator  response  \’"/,s\"\n' 
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buff); 

return  (SP_ERROR): 

} 


enum  TrainStatus 
GetTrainStatus(train_id) 
int  train. id; 

{ 

MsgCPITrainStatus  msg;  /♦  data  structure  for  message  construction  •/ 
char  buf f tBUFFSI2E] ;  /*  buffer  for  outgoing  message  */ 

int  n;  /*  return  status  from  RecvMsgTimed  •/ 

msg. client.id  =  client.id;  /*  identifier  of  this  client  */ 
msg.seq.num  =  seq.num;  /*  voting  sequence  number  •/ 
msg.train.id  =  train.id; 

CreateHsgCPITrainStatusCbuff ,  ftmsg) ; 
if  (SendMsg(chan,  buff,  strlcn(buff ))  <  0)  { 
perror("GetTrainStatus :  SendKsg  failed"); 

> 

if  ((n  =  RecvMsgTimed(chan,  buff,  BUFFSIZE,  qUERY.TIMEOUT) )  <  0) 
return  (TS.ERROR) ; 

/*  response  successfully  received  from  simulator  and  stored  in  buff  */ 

switch  (buff [O] )  { 
case  ’c’;  return  (TS.CRASHED) ; 
case  ’r’:  return  (TS.RUNIfIFG)  ; 
default : 

buffCn]  =  ’\0’; 

fprintf (stderr ,  "GetTrainStatus ;  unknown  simulator  response  \"y,s\"\n", 
buff); 

return  (TS.ERRQR) ; 

} 

} 


enum  TrainMotion 
GetTrainMotion(train_id) 
int  train. id; 

■C 

MsgCPITrainMotion  msg;  /*  data  structure  for  message  construction  */ 
char  buf f [BUFFSIZE] ;  /♦  buffer  for  outgoing  message  */ 
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int  n;  /♦  return  status  from  RecvMsgTimed  */ 


msg . client_id  =  client_id;  /*  identifier  of  this  client  •/ 
msg.seq.num  =  seq.num;  I*  voting  sequence  number  ♦/ 
msg.train_id  =  train_id; 

CreateMsgCPITrain>Iotion(buff ,  4osg) ; 
if  (SendHsgCchan,  buff,  strlen(buff ) )  <  0)  { 
perrorC'GetTrainMotion:  SendMsg  failed"): 

} 

If  ((n  =  RecvMsgTimed(chan,  buff,  BUFFSIZE,  QUERY.TIMEOUT) )  <  0) 
return  (TM_ERR0R) ; 

/•  response  successfully  received  from  simulator  and  stored  in  buff  •/ 

switch  (buff[0])  {. 
case  's’;  return  (TM_STQPPED) ; 
case  'm':  return  (TM.MOVING) ; 
default : 

buffCn]  =  ’\0’; 

fprintf  (stderr,  "GetTrainMotion:  unknown  simulator  response  \"*/,E\"\n", 
buff )  ; 

return  (TM.ERROR) ; 

> 

} 


/*  «*****i^*«4r*4>«4^*****  *******  ***«*4>****4i«****4i4>*****«iti***«4>*******/ 

/*  Voting  Sequence  Sumber  ♦/ 
int 

SetSeqlIuTOber(new_val) 
int  new_val; 

{ 

if  (new_val  <  0) 
return  (-1); 
else  { 

seq.num  =  new_val; 
return  (seq_num); 

> 

> 


int 


NesSeqlTiimber  ( ) 

i 

retiirn  (++seq_iixun) ; 

} 
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acitest(l) 


Neune 

acitest  -  manual  test  of  CPI  interface  in  Trainset 
Syntax 

acitest  [  -d  ]  C  simhost  [  samnum  ]] 

Description 

acitest  is  an  example  program  included  with  the  Trainset 
software.  Its  source  code  illustrates  the  use  of  the  upper 
layer  (called  the  ACI)  of  the  Control  Program  Interface 
(CPI).  When  invoked  and  connected  to  a  running  railroad 
simulation  (see  tsim(l)),  it  enables  a  user  to  interactively 
perform  each  ACI  command  and  query.  The  effects  of  each 
action  may  be  observed  using  the  monitor  programs  tspanel(l) 
and  tsviewd ) . 

Options  and  Arguments 

-d  Causes  the  state  information  received  from  a  simulation 
to  be  printed  during  startup. 

simhost 

Specifies  the  name  of  a  host  that  is  running  a  simula¬ 
tion  of  a  railroad.  If  an  empty  string  is  specified, 
the  local  host  is  used.  If  the  simhost  argument  is 
omitted,  a  value  is  requested  interactively. 

simnum 

An  integer  that  determines  which  invocation  of  the  tsim 
simulator  (at  the  indicated  host)  is  to  be  used.  The 
default  value  is  0.  The  monitor  programs  cind  the 
desired  invocation  of  tsim  should  use  the  same  value 
for  number. 


See  Also 

ts(l),  tsim(l),  tspanel(l),  tsviewd). 
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Sane 

ts  -  launch  Trainset  applications 
Syntax 

ts  [  flags ...  3 

ts  -edit  [  file  ]  [  -layout  file  ]  [  -tsroot  dir  ]  [  Xll- 
options  3 

Description 

ts  invokes  (‘‘launches’’)  applications  related  tc  the  Train- 
set  railroad  simulation  softHare  in  a  computing  environment 
that  may  involve  a  heterogeneous  network  of  computing  sys¬ 
tems.  With  no  options,  ts  typically  starts  a  demonstration 
consisting  of  a  simulation  of  a  sample  railroad,  an  Xll 
application  that  graphically  displays  the  current  state  of 
the  railroad,  and  another  Xll  application  that  provides  for 
manual  control  of  the  railroad,  ts  options  enable  the  user 
to  select  which  applications  are  to  be  launched,  choose  the 
railroad  layout  to  be  simulated,  specify  the  host  to  launch 
from,  etc. 

Programmers  may  write  software  that  interacts  with  Trainset, 
including  programs  that  automatically  control  a  railroad  and 
custom  versions  of  the  basic  Trainset  software,  ts  provides 
a  configuration  mechanism  for  adding  launch  information 
describing  such  programs  to  its  database. 

When  invoked  with  -edit  as  the  first  command-line  option,  ts 
invokes  the  tsed  editor  for  railroad  layouts  eind  launches  no 
other  application.?.  The  options  -tsroot  and  -layout  are 
recognized  by  ts  in  the  case  of  -edit,  and  may  appeeir  either 
in  an  environment  variable  TSQPTS  or  on  the  command  line, 
file  names  the  layout  data  file  tc  be  edited,  file  may  be 
presented  as  the  second  command  line  argument  if  it  does  not 
begin  with  a  dash  ‘-’.  It  may  also  be  provided  using  the 
-layout  option,  -tsroot  specifies  the  tsed  search  paths  for 
layout  data  files,  as  discussed  in  Search  Paths  below.  In 
addition,  any  additional  options  on  the  command  line,  in 
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paurticular  options  recognized  by  Xll,  2Lre  passed  on  to  tsed. 
Applications 

Trainset  consists  of  application  programs  that  support 
interaction  with  a  simulated  railroad.  Railroads  are 
represented  by  layouts  that  consist  of  trains  and  blocks  of 
track.  Users  of  Trainset  may  write  programs  that  use  the 
Control  Program  Interface  (CPI)  to  control  such  a  railroad. 
For  more  information,  see  the  meinuals  for  Trainset. 

The  standard  applications  that  comprise  Trainset  include  the 
following. 

tsim 

tsed 


tsview 


t span el 


Simulator  of  railroad  layouts. 

Editor  for  interactive  creation  and  modifica¬ 
tion  of  a  layout, 

A  graphical  display  of  the  state  of  a  layout 
during  a  simulation. 

A  graphical  control  panel  for  manually 
operating  a  layout’s  trains  and  switch 
blocks . 


In  addition,  programs  that  demonstrate  the  CPI,  including 
acitest  and  demo,  are  provided  in  the  Trainset  distribution. 

Control  Codes 

In  ts,  applications  aire  referenced  by  control  codes  that  are 
strings  consisting  of  an  uppercase  letter  optionally  fol¬ 
lowed  by  any  combination  of  lowercase  letters,  digits, 
underscores  and  periods.  The  following  control  codes  are 
conventionally  defined  in  the  main  configuration  file  for 
ts : 


Sim,  S,  Tsim  Trainset  railroad  simulator. 
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Pajiel,  P,  Tspanel 

Control  panel  application. 

Viever,  V,  Tsvies 

Viever  application  for  observing  a  simula¬ 
tion  . 

Acitest  program  that  allous  manual  experimen¬ 
tation  with  CPI  interface  features. 

Demonstration  of  the  CPI  interface  discussed 
in  the  Trainset  manual. 

Any  of  the  ts  options  -args.  -delay,  -direct,  -display, 
-host,  -tsroot,  -xterm  and  -xtermargs  can  be  localized  to 
apply  to  a  specific  application  by  prefixing  that  option 
with  the  appropriate  control  code(s) .  For  example,  either 
‘Sira:-host  loki’  or  ‘S:-host  loki’  specifies  that  the  simu¬ 
lator  should  be  launched  at  the  site  loki.  Also, 
‘PV;-display  thor:0.0’  causes  the  peinel  and  viewer  applica¬ 
tions  to  display  graphics  output  on  the  XI 1  server  thor;0.0, 
Arbitrary  arguments  can  be  passed  to  applications  using  the 
-args  option  prefixed  by  the  appropriate  control  code,  e.g., 
‘Myprog:-args  "-level  4  -trace"’.  Quoting  (e.g.,  using 
enables  spaces  to  be  included  in  the  argument  string. 

If  the  colon  that  terminates  a  prefix  is  followed  immedi¬ 
ately  by  a  character  (e.g.,  dash  '-’)  that  cannot  be  part  of 
a  control  code  name,  then  that  colon  may  be  omitted.  For 
example,  ‘Sim-host  loki’  is  equivalent  to  ‘Sira:-host  loki’. 

An  aliaj  facility  is  provided  for  associating  multiple  con¬ 
trol  codes  with  a  single  application.  Aliases  may  be 
declared  in  configuration  files  (discussed  below)  or  by 
using  the  -alias  option.  The  alias  feature  can  be  used  to 
change  the  associations  between  control  'odes  and  applica¬ 
tions.  For  exsonple,  suppose  that  a  control  code 
Train_control_2  is  associated  with  an  application  that  has 


Acitest,  A 


Demo ,  D 
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been  written  locally.  Then  the  ts  option  '-alias 
T=Train_control_2 '  assigns  the  control  code  T  to  represent 
that  local  application.  Train_control_2  is  a  better  identif¬ 
ier,  but  the  alias  T  is  more  convenient  as  a  prefix.  Also, 
‘-alias  Demo=T'  could  be  used  to  associate  the  control  code 
Demo  with  that  local  application  instead  of  the  standard 
Trainset  demonstration  program. 

The  -dup  option  may  be  used  to  invoke  multiple  copies  of  an 
application.  This  feature  supports  the  launching  of  repli¬ 
cated  programs,  -dup  clones  the  launch  information  gathered 
so  far  for  the  application  in  question  cind  associates  a  con¬ 
trol  code  with  the  copy.  The  launch  attributes  in  the  two 
copies  may  thereafter  be  modified  independently. 

Search  Paths 

The  directory  tsroot  identifies  the  location  of  the  Trainset 
installation  in  the  local  file  system.  Tsroot  may  be  speci¬ 
fied  as  the  value  of  an  environment  variable  TSROOT  or  on 
the  command  line  using  the  -tsroot  option. 

Ts  searches  for  its  own  configuration  files  in  the  direc¬ 
tories  .,  ./lib,  tsroot  and  tsroct/lib  (in  that  order). 

Layout  data  files  for  a  simulation  are  sought  in  the  direc¬ 
tories  .,  ./layouts,  tsroot,  tsroot/iayouts  and 
tsroot/trainset/layouts .  The  default  extension  '.1  is 
'"pended  (if  omitted)  to  a  layout  data  file  name  by  Trainset 
applications  and  searching  is  repeated  if  a  file  with  the 
given  name  was  not  found.  If  no  layout  data  file  is  speci¬ 
fied,  the  file  tsroot/layouts/sample.l  is  used. 

Binaries  for  Trainset  applications  are  sought  using  the 
environment  variable  PATH  as  usual. 

Launching  Applications 

Unless  the  -edit  option  is  specified,  ts  gathers  infoimation 
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from  the  following  sources,  in  order,  before  launching 

applications . 

Main  configuration  file 

This  file  associates  control  codes  with  applications, 
contains  invocation  information  for  applications  (e.g., 
name  of  executable  and  default  arguments)  and  provides 
a  default  list  of  applications  to  be  launched.  See 
ts.config(5)  for  the  file  format.  The  name  of  the  main 
configuration  file  may  be  specified  with  the  -config 
option.  Th‘)  default  main  configuration  file  is 
tsroot/ts .  coT'f  ig . 

Auxiliary  configuration  files 

One  or  more  additional  configuration  files  may  be 
designated  to  supplement  the  main  configuration  file. 
These  are  specified  by  the  ts  options  -confign  where  n 
is  a  single  digit.  Auxiliary  configuration  files  are 
processed  in  increasing  order  of  a.  The  values  of  n 
need  not  be  contiguous.  Auxiliary  configuration  files 
enable  individual  users  and  groups  of  users  to  install 
their  own  applications  euid  customize  launching  informa¬ 
tion  for  applications  that  appear  in  the  main  confi- 
giiration  file.  Attributes  for  the  launch  are  either 
overridden  or  appended  as  appropriate.  If  a  non-empty 
list  of  applications  to  be  launched  is  included  in  an 
auxiliary  configuration  file,  it  overrides  any  prior 
list.  There  are  no  default  auxiliary  conf igxiration 
files. 

Environment  variables  TSROOT,  TSOPTS  and  DISPLAY 

If  there  is  an  environment  variable  TSROOT,  it  is 
treated  as  the  default  value  for  tsroot  (see  Search 
Paths  above) .  If  there  is  an  environment  variable 
TSOPTS,  it  is  treated  as  a  list  of  ts  options  that  are 
parsed  prior  to  the  options  specified  on  the  command 
line.  If  there  is  an  environment  variable  DISPLAY  with 
value  XI 1-display,  then  the  option  -xtermargs  XI 1- 
display  is  implicitly  processed  just  prior  to  any 
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optiens  in  TSQPTS. 

Command  line  options 

See  Options  below. 

The  signif iccince  of  the  ordering  above  is  that  later  values 
override  or  are  appended  to  earlier  values.  For  example,  a 
-host  option  in  TSQPTS  overrides  any  HOST  entries  in  confi¬ 
guration  files,  and  'Sim:-args  "-window  S" ’  on  the  command 
line  appends  to  the  arguments  for  the  Sim  application  that 
were  collected  from  configuration  files  and  TSOPTS. 

Launching  at  a  remote  host  is  accomplished  by  invoking  ts  at 
the  remote  site,  as  described  in  ts .remote(8) .  The 
information  that  is  passed  to  a  remote  ts  consists  of  an 
options  list  that  is  assembled  by  the  local  ts  after  scan¬ 
ning  the  local  sources  listed  above.  That  options  list  con¬ 
sists  of  the  following. 

A  -launch  option  listing  the  applications  to  be 
launched  at  that  site. 

A  -display  option,  unless  no  -display  attribute  was 
given  and  there  is  no  local  DISPLAY  environment  vari¬ 
able  . 

Any  applicable  control-code  specific  -display  options, 
-simhost  and  -simniua  options. 

Any  local  command-line  options  that  remain  after  remov¬ 
ing  -host  and  -launch  (+)  options. 

The  remote  ts  gets  its  launch  information  first  from 
remote-site  configuration  files,  then  from  remote-site 
environment  variables  and  finally  from  the  options  list  that 
was  assembled  at  the  local  site.  (Note  that  values  for 
attributes  such  as  -delay  and  -tsroot  may  be  passed  to  the 
remote  site  only  if  they  are  specified  in  local  command-line 
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options , ) 

ts  provides  two  methods  for  launching  applications, 
xterm  Method 

If  the  configuration  file  attribute  XTERM  for  an  appli¬ 
cation  is  a  string  of  positive  length  or  if  the  -xterm 
option  is  used,  then  the  application  is  invoked  in  an 
xtarm(l)  cindos  that  is  created  for  that  purpose.  That 
application’s  standard  input  amd  output  will  be  associ¬ 
ated  with  the  xterm  window.  Arguments  can  be  passed  to 
xterm  using  the  -xtermargs  option  discussed  below. 

Direct  Method 

Applications  that  are  launched  without  using  the  xterm 
method  are  invoked  asynchronously  by  the  ts  process, 
and  share  that  process’s  standard  output.  The  standard 
input  for  all  such  applications  is  /dev/null,  except 
the  last  application  launched  by  the  direct  method 
inherits  the  ts  process’s  stemdard  input  as  well  as 
standard  output.  Thus,  an  interactive  application 
(e.g.,  acitest(l))  may  be  launched  using  the  direct 
method  provided  that  it  the  last  such  application 
specified.  See  the  Examples  section. 

xterm  is  the  default  launch  method.  The  direct  method  is 
currently  implemented  for  the  local  host  only,  i.e.,  the 
host  at  which  the  ts  command  was  entered.  Thus,  any  -host 
options  are  ignored  for  applications  launched  by  the  direct 
method. 

Options 

-alias  controll=control2 

Declares  the  control  code  controll  to  be  an  alias  for 
the  control  code  control2.  The  two  codes  may  then  be 
used  interchangeably  for  referring  to  the  application 
launch  attributes  associated  with  control2,  if  there  is 
such  an  application.  The  symbol  '=’  is  optional. 
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-dup  controll=control2 

Hake  a  copy  controll  of  the  application  launch  attri¬ 
butes  associated  with  control2.  Since  the  two  control 
codes  represent  different  copies,  a  change  in  the 
attributes  referenced  by  controll  will  have  no  effect 
on  the  attributes  referenced  by  control2.  This  is  use¬ 
ful  for  invoking  multiple  copies  of  the  same  applica¬ 
tion,  e.g.,  parallel  copies  of  the  same  CPI  program  for 
controlling  a  railroad.  The  symbol  '=’  is  optional. 

-args  arglist 

Provides  program-specific  arguments  to  be  passed  to 
applications.  This  option  is  ordinarily  prefixed  by 
control  codes,  e.g.,  ‘Sim: -args  "-update  O.S'”. 

-conlig  filename 

Specifies  the  name  of  the  main  configuration  file, 
-confign  filename 

Specifies  the  name  of  the  nth  auxiliary  configuration 
file. 

-delay  seconds 

Specifies  an  integer  number  of  seconds  to  pause  just 
after  launching  each  application. 

-direct 

Specifies  that  applications  should  be  launched  using 
the  direct  method. 

-display  XI 1-display 

Indicates  the  display  for  Xll  output.  The  environment 
variable  DISPLAY  is  set  to  Xll-display  for  the  applica¬ 
tions  that  are  launched,  and  '-display  Xll-display'  is 
appended  to  the  list  of  arguments  for  xterm.  The 
latter  effect  is  approximately  equivalent  to  -xtermargs 
"-display  Xll-display";  this  does  not  affect  applica¬ 
tions  launched  by  the  direct  method,  but  such  applica- 
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tions  cem.  still  obtain  the  value  XI 1-display  by 
examining  the  environment  variable  DISPLAY. 

-edit  filename 

Invoke  the  tsed  editor  to  create  or  modify  a  layout 
data  file  of  blocks  and  trains  to  be  simulated.  If 
filename  is  a  relative  path  (does  not  begin  Bith 
a  file  with  that  naime  is  seeurched  for  using  the  search 
path  for  layouts.  If  such  a  file  is  found,  its  path  is 
passed  to  tsed  for  modification.  Otherwise,  filename 
is  passed,  so  that  a  new  layout  data  file  with  that 
name  may  be  created  relative  to  the  current  working 
directory  The  -edit  option  should  not  be  used  in  com¬ 
bination  with  any  other  ts  options. 

-host  hostname 

ts  seeks  configuration  files  aind  invokes  executables  at 
the  site  hostname,  except  when  specifically  overridden 
by  other  ts  options. 

-layout  filename 

The  railroad  layout  to  be  simulated  is  described  in 
filename,  which  must  be  in  the  format  produced  by  tsed. 
See  Search  Paths  above. 

-launch  control. .  . 

Specifies  that  the  indicated  applications  (only)  should 
be  invoked.  The  default  list  of  applications  to  launch 
is  determined  by  the  first  lines  of  configuration 
files . 

-quorum  n 

Sets  the  simulator  voting  quorum  value  to  n. 

Equivalent  to  'Sim:-args  "-quorum  n" ’ . 

-tsroot  dirnaune 

Specifies  the  value  of  tsroot. 

-simhost  hostname 
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Specifies  the  host  on  shich  to  invoke  the  simulator. 
Equivalent  to  ‘Sim:-host  hostncuoe’. 

-simnum  number 

number  determines  which  well-known  port  is  to  be  used 
when  initializing  communication  with  a  railroad  simula¬ 
tion.  Permissible  values  for  number  are  installation- 
dependent  and  typically  include  the  range  0  to  99. 
Applications  that  are  la\inched  with  a  given  value  for 
number  cem  only  connect  with  a  simulation  that  was 
launched  with  that  same  -simnum  value  number;  thus, 
multiple  railroad  simulations  may  be  run  simultaineously 
on  the  same  host  if  they  use  different  values  for 
number.  It  is  convenient  to  assign  several  unique 
values  of  number  to  each  Trainset  user  in  order  to 
avoid  collisions  among  users. 

-update  seconds 

Specifies  the  frequency  that  the  simulator  sends  state 
update  reports  to  graphics  monitor  programs  (control 
panel  and  viewer),  seconds  may  be  a  decimal  value, 
e.g.,  0.5.  Equivalent  to  ‘Sim;-axgs  "-update 
seconds" ’ . 

-window  seconds 

Sets  the  simulator  voting  window  value  to  seconds. 
Equivalent  to  'Sim:-args  "-window  seconds"’. 

-xterm 

Specifies  that  applications  should  be  launched  using 
the  xterm  method. 

-xtermargs  args 

Provides  arguments  to  be  passed  to  xterm(l),  for  appli¬ 
cations  to  be  launched  using  the  xterm  method.  Enclose 
args  in  quotes  if  it  contains  embedded  spaces . 

+control .  .  . 

Same  as  -launch  control. 
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axgs  Any  options  that  are  not  listed  above  axe  passed  to 
xtermd)  for  applications  launched  using  the  iterm 
method.  Thus,  the  options  args  is  approximately 
equivalent  to  -xtermargs  "args". 


Examples 

Start  the  standard  programs  (as  listed  in  in  configuration 
files)  using  their  default  methods.  Use  the  default  layout 
data  file  to  define  the  railroad  being  simulated.  Send  all 
graphics  output  to  the  Xll  server  specified  in  the  environ¬ 
ment  variable  DISPLAY,  and  interpret  any  options  listed  in 
the  environment  variable  TSOPTS. 

ts 


Seek  a  file  oval.l  as  described  in  Search  Paths  above  for 
layout  data  files.  If  it  is  found,  then  start  the  standard 
programs  as  before,  sith  the  simulator  tsim  using  that  file 
oval.l  to  define  the  railroad  layout. 


ts  -layout  oval.l 


Stcirt  the  standard  programs  as  before,  except  send  output 
for  the  Panel  application  to  thor:0  stnd  send  all  other 
graphics  output  to  the  Xll  server  loki:0.  Send  updated 
information  to  any  running  graphics  monitor  programs  (e.g., 
Viewer  and  Panel)  every  3/4  second. 

ts  -display  loki:0  -update  .75  Panel : "-display  thor:0" 
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Launch  the  applications  S,  V  and  A  using  their  default 
methods.  Unless  these  control  codes  have  been  reassigned, 
they  refer  to  the  Simulator,  Viewer  and  Acitest  applica¬ 
tions  . 


ts  +SVA 


Launch  the  applications  S,  V  and  A  using  the  direct  method. 
Output  for  the  various  applications  will  be  intermingled  on 
the  screen.  Since  A  is  specified  last,  that  application  can 
be  operated  interactively.  The  direct  method  is  useful  for 
debugging  new  applications  and  for  systems  that  do  not  sup¬ 
port  the  program  xterm(l). 

ts  +SVA  -direct 


Bugs 

The  remote  invocation  facility  is  not  currently  implemented. 

Unpredictable  results  may  occur  if  a  control  code  is  made  a 
duplicate  of  itself. 


See  Also 

tsed(l),  tsira(l),  tspanel(l),  tsview(l),  ts . conf ig(5) , 
ts .remote(8) . 
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Hame 

tsed  -  Trainset  layout  editor 
Syntax 

tsed  [  file  ]  [  -layout  file  ]  [  -tsroot  dir  ]  [  Xll-options 

] 

Description 

tsed  is  an  interactive  graphics  editor  for  defining  and 
modifying  railroad  layouts  for  use  in  the  Trainset  railroad 
simulation  softsare.  On  startup,  tsed  displays  two  windows : 
(1)  a  canvas  window  on  which  the  layout  is  created.  The 
window  contains  a  set  of  pulldown  menus  along  the  top,  a 
message  area  at  the  bottom,  and  is  overlaid  with  an  align¬ 
ment  grid,  and  (2)  a  tools  window  consisting  of  icons 
representing  the  operations  available  for  creating  and  modi¬ 
fying  blocks  and  trains. 

With  no  file  or  options  specified,  tsed  starts  with  a  blank 
unnamed  layout.  The  options  -tsroot  and  -layout  are  recog¬ 
nized  by  tsed  eind  may  appeau:  either  in  the  environment  vari¬ 
able  TSOPTS  or  on  the  command  line,  file  names  the  layout 
data  file  to  be  edited,  file  may  be  presented  as  the  second 
command  line  argument  if  it  does  not  begin  with  a  dash 
It  may  also  be  provided  via  the  -layout  option,  -tsroot 
identifies  the  location  of  the  ts  installation  in  the  file 
system  and  is  used  to  determine  the  location  of  auxiliary 
files  needed  by  tsed.  These  are  searched  for  in  tsroot, 
tsroot/lib  and  tsroot/trainset/lib  if  tsroot  is  specified 
and  then  according  to  the  PATH  environment  variable .  tsed 
uses  tsroot  to  search  for  layout  data  files  in  the  following 
order;  .,  ./layouts,  tsroot,  tsroot/layouts  and 
tsroot/trainset/layouts .  The  default  extension  is 

appended  to  a  layout  data  file  name  and  the  seeo'ch  repeated 
if  the  given  file  was  not  found. 

tsed  also  recognizes  the  standard  Ill  application  options. 
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Layout  Tools 

The  layout  tools  lie  in  tso  columns  of  icons  in  the  tools 
window  cind  are  called  (top  to  bottom,  left  to  right)  Select, 
Erase,  Straight  Block,  Station  Block,  Arc  Block  1,  Arc  Block 
2,  Cross  Block,  Join  Block,  Switch  Block  1,  Switch  Block  2, 
Train,  eind  Rotate.  Select,  Erase,  and  Rotate  manipulate 
existing  blocks.  Straight  Block  and  Station  Block  create 
linear  blocks.  Arc  Block  1  and  Arc  Block  2  create  circular 
arc  blocks.  Cross  Block,  Join  Block,  Switch  Block  1,  and 
Switch  Block  2  create  fixed  size  iconic  blocks.  The  current 
tool  is  shown  highlighted  by  inverting  its  colors  and  is  set 
by  clicking  on  it.  Clicking  the  left  mouse  button  in  the 
canvas  area  invokes  the  current  layout  tool,  tsed  provides 
the  following  layout  tools: 

Select  Move  block  labels  by  dragging  within  their 

boundaries.  Select  a  block  by  clicking  on  it 
whether  or  not  it’s  already  selected  and  dis¬ 
card  any  other  selection. 

Erase  Remove  a  block  or  train  from  a  layout  by 

clicking  on  it. 

The  four  tools.  Straight  Block,  Station  Block,  Arc  Block  1, 
and  Arc  Block  2,  create  regular  and  station  blocks  using  a 
drag  technique  to  determine  the  position  of  the  head  and 
tail  terminators  of  the  block.  If  the  start  point  or  end 
point  of  the  drag  is  within  a  few  pixels  of  the  terminator 
of  an  existing  block,  tsed  attempts  to  establish  a  connec¬ 
tion.  In  such  a  case,  tsed  constrains  the  slope  of  the  new 
block  to  match  the  slope  of  the  existing  block  at  the  termi¬ 
nator. 

Straight  Block  Create  a  straight  regular  block.  The  block 

is  constrained  to  be  vertical,  horizontal,  or 
at  +  or  -  45  deg  diagonal . 

Station  Block  Create  a  station  block.  Created  and  con¬ 
strained  in  the  same  way  as  straight  block 
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above . 

Arc  Block  1  Create  a  circular  arc  regular  block.  The 

start  point  of  a  drag  determines  the  location 
of  the  head  terminator  of  the  block.  The 
radius  of  the  circular  arc  is  two  grid  divi¬ 
sions.  The  extent  of  the  arc  is  determined 
by  the  angle  given  by  the  head  terminator  and 
the  end  point  of  the  drag.  The  extent  of  the 
arc  is  constrained  to  be  a  multiple  of  45 
deg. 

Arc  Block  2  The  same  as  Arc  Block  1  but  with  a  radius  of 
four  grid  divisions. 

The  four  tools.  Cross  Block,  Join  Block,  Switch  Block  1,  and 
Switch  Block  2,  create  iconic  blocks,  blocks  that  have  a 
fixed  size  and  shape.  They  are  created  by  simply  clicking 
the  mouse,  whose  cursor  takes  the  form  of  the  icon  for  the 
current  tool.  Along  the  outer  circle  of  such  a  cursor  are 
enlarged  points  called  hot  spots  at  which  connections  with 
other  blocks  can  be  made.  When  a  connection  is  established, 
the  newly  created  iconic  block  is  constrained  so  that  the 
slope  at  the  connecting  hot  spot  and  the  slope  at  the  exist¬ 
ing  terminator  agree,  tsed  does  not  establish  more  than  one 
connection  when  an  iconic  block  is  created. 

Cross  Block  Create  a  cross  block. 

Join  Block  Create  a  join  block. 

Switch  Block  1  Create  a  switch  block  whose  turn  head  is  45 
deg  counter  clockwise  from  its  straight  head. 

Switch  Block  2  Create  a  switch  block  whose  turn  head  is  46 
deg  clockwise  from  its  straight  head. 

Train  Create  a  train.  The  drag  operation  for 

creating  a  train  begins  at  the  position 
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desired  for  the  head  end  of  a  train,  contin¬ 
ues  along  the  blocks  to  be  occupied  by  that 
train,  and  stops  at  the  position  desired  for 
that  train’s  tail  end.  The  head  end  of  a 
train  is  indicated  by  cin  eingle  bracket,  auid 
the  tail  end  is  indicated  by  a  square 
bracket.  All  blocks  that  are  occupied  by  a 
train  are  highlighted.  The  head  end  of  a 
train  is  constrained  to  start  in  a  regular  or 
station  block. 

Rotate  Rotate  an  iconic  block  clockwise  about  its 

center  to  the  next  hot  spot. 


Pulldown  Menus 

The  pulldown  menus  File  and  Customize  lie  in  a  menu  bar 
along  the  top  of  the  canvas  window  They  contain  commands 
which  you  execute  by  pulling  down  the  menu  and  releasing  the 
mouse  button  on  the  command. 


The  File  menu  contains  the  following  commands  to  operate  on 
f  .lies ; 


Kew 


Open 


Save 


Save  As  .  .  . 


Close 


Clear  the  current  layout  and  create  a  new 
empty  layout,  requesting  a  layout  name  from 
the  user. 

Open  an  existing  layout  using  a  layout  data 
file  typed  by  the  user.  The  search  is  the 
same  as  specified  above. 

Save  the  current  layout  under  the  current 
file  name,  if  one  exists.  If  one  does  not, 
then  it  is  the  same  as  executing  Save  As  . . . 

Save  the  current  layout  under  a  new  name 
specified  by  the  user. 

Close  the  current  layout  and  clear  the  can- 


114 


Exit  the  application  after  first  checking  for 
any  unsaved  changes. 

The  Customize  menu  contains  the  folloHing  commands  to  alter 
the  appearance  of  the  current  layout  and  the  attributes  of 
the  blocks  contained  within; 

Chcinge  Block  Attributes 

Change  the  attributes  of  a  selected  block 
(.See  Select  above).  If  no  block  is  selected, 
a  warning  beep  is  sounded. 

Change  Default  Block  a*- tributes 

Change  the  default  creation  attributes  of  a 
block  type.  This  is  a  hierarchical  menu 
whose  submenu  axe  the  various  block  types. 

Labels  Change  the  appearance  of  the  labels  on  the 

current  layout.  This  is  a  hierarchical  menu 
whose  submenu  entries  are:  Barnes  --  Labels 
are  block  names;  Speeds  --  Labels  indicate 
the  minimum,  maximum,  aoid  stop  velocities 
associated  with  each  block;  Hide  Labels  -- 
Hide  the  labels  in  the  current  layout . 


Hide/Show  Grid  Hide  (Show)  the  grid  lines  in  the  canvas  win 
dow.  Bote  that  this  does  not  turn  the  grid 
alignment  and  constraints  off ,  it  merely 
removes  the  grid  from  view. 


Files 

tsroot/lib/tsed . uid 
See  Also 

ts(l),  layout  data  file  description 


Bugs  /  Restrictions 


tsed(l) 


Due  to  a  bug  in  the  DEC  Xqdsg  server,  tsed  causes  the  X 
server  to  crash  »hen  using  the  Arc  Block  1  and  Arc  Block  2 
tools  with  X  servers  from  Ultrix  4.0  and  Ultrix  4.1.  There 
is  no  problem  in  Ultrix  4,2  and  the  Ultrix  4.2  X  server  can 
be  used  with  Ultrix  4.0  and  4.1. 
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Name 

tsim  -  Trainset  railroad  simulation 
Syntax 

tsim  [  flags, . .  ] 

Description 

tsim  simulates  a  Trainset  railroad.  The  Trainset  software 
consists  of  this  simulator,  an  interactive  graphics  editor 
tsed(l)  for  defining  railroad  layouts  jind  graphics  monitor 
programs  tspanel(l)  and  tsviewd)  for  displaying  the  state 
of  the  railroad  and  manually  controlling  it.  See  The  Train- 
set  Railroad  Simulation  for  more  information. 

The  programs  tsim,  tspanel  and  tsvieu  are  ordinarily  invoked 
using  the  launch  program  ts(l). 

Interfaces 

tsim  provides  three  interfaces.  The  control  program  inter¬ 
face  (CPI)  is  used  by  computer  programs  that  control  a 
Trainset  railroad.  The  CPI  is  fully  documented  and  enables 
researchers  and  students  to  write  control  programs  for 
investigating  issues  such  as  real-time  computing  <ind  fault- 
toleramce.  Programs  such  as  acitestCl)  that  illustrate  the 
CPI  are  included  in  the  software  distribution. 

The  other  two  interfaces  are  used  internally  by  Trainset. 
They  are:  the  layout  interface,  for  reading  files  that 
describe  a  railroad  and  its  initial  state,  as  produced  by 
tsed;  and  the  monitor  interface,  for  communication  between 
tsim,  tspanel  and  tsview. 

Options 

-layout  layoutfile 

The  railroad  layout  to  be  simulated  is  described  in  the 
layout  data  file  layoutfile,  which  must  be  in  the  for- 
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mat  produced  by  tsed.  Specify  a  complete  absolute  or 
relative  path  for  layoutfile. 

-quorum  n 

Sets  the  voting  quorum  value  for  this  simulation  to  n. 
-simnum  number 

Number  determines  Bhich  Bell-knosn  ports  cire  to  be  used 
Bhen  other  programs  are  initializing  communication  with 
this  simulation.  Permissible  values  for  number  are 
installation-dependent  and  typically  include  the  range 
0  to  100.  Multiple  inst^lnces  of  tsim  may  be  run  simul¬ 
taneously  on  the  same  host  if  they  use  different  values 
for  number. 

-update  seconds 

Specifies  the  frequency  that  tsim  is  to  send  state 
update  reports  to  graphics  monitor  programs.  Seconds 
may  be  a  decimal  value,  e.g.,  0.5. 

-window  seconds 

Sets  the  voting  window  value  for  this  simulation  to 
seconds . 

See  Also 

ts(l),  tsed(l),  tspanel(l),  tsvieB(l),  acitest(l). 
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Name 

tspamel,  tsview  -  Trainset  railroad  monitor  programs 
Syntax 

tspanel  [  -simhost  hostnaune  ]  [  -simnum  number  ]  [  -tsroot 
dir  ] 

tsvieo  C  -simhost  hostname  ]  [  -simnum  number  ]  [  -tsroot 
dir  ] 

Description 

tspanel  is  a  graphical  interface  lor  manually  controlling 
and  displaying  quantitative  state  information  about  a  simu¬ 
lation  of  a  Trainset  railroad,  tsvieu  displays  the  state  of 
a  Trainset  railroad,  including  location  of  trains  a;id  set¬ 
tings  of  switches .  These  programs  enable  a  user  to  estab¬ 
lish  initial  conditions  of  train  motion  and  switch  settings 
in  a  railroad  and  to  monitor  the  progress  of  a  simulation. 
Each  program  receives  regular  reports  of  the  railroad 
layout’s  state  from  the  Trainset  simulator,  tsim(l).  See 
The  Trainset  Railroad  Simulation  for  more  information. 

tspanel  and  tsview  are  ordinarily  invoked  using  the  la\inch 
program  ts(l ) . 

Options 

-simhost  hostname 

Specifies  the  host  that  is  running  the  simulator  tsim. 
-simnum  number 

number  determines  which  invocation  of  the  tsim  simula¬ 
tor  (at  the  indicated  host)  is  to  be  used.  The  monitor 
programs  and  the  desired  invocation  of  tsim  should  use 
the  same  value  for  number. 

-tsroot  dir 

(DECwindows  implementation  only.)  Specifies  directory 
for  locating  uid  startup  file,  e.g.,  tsroot/tsviow.uid 
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or  tsroot/lib/tsvieo.uid. 
Limitations 

Currently  implemented  on  DECwindons  only. 

See  Also 

ts(l) ,  tsim(l) . 
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